Plugins API

[olastor]

In olastor/age-plugin-fido2-hmac#20 I created the PoC mentioned in #16 and while doing that I added a simple plugin API to a fork of typage (see olastor@156a9b1). I am wondering if there could be an official plugin API in this project. I tried to create a simple implementation that is close to FiloSottile/age#580 .

Every plugin would need to implement the following data structure:

export interface Plugin<Recipient, Identity> {
  name: string
  handleRecipient: (recipientBytes: Uint8Array) => Recipient
  handleIdentityAsRecipient: (identityBytes: Uint8Array) => Recipient
  handleIdentity: (identityBytes: Uint8Array) => Identity
  wrapFileKey: (recipient: Recipient, fileKey: Uint8Array) => Stanza | Promise<Stanza>
  unwrapFileKey: (identity: Identity, stanzas: Stanza[]) => Uint8Array | Promise<Uint8Array | null> | null
}

For the Encrypter / Decrypter classes, you'd then need to call .registerPlugin(plugin). There'd also be a new addIdentity() method in the encrypter that uses handleIdentityAsRecipient.

There are probably many ways this API could be implemented and the code I created in the fork is still a bit "sketched", lacking validations, tests etc. If a modified version of this would be useful for having in the main package, I could look into polishing it and creating a PR, though. But maybe also a totally different way of doing it could be considered.

[FiloSottile]

Thank you for opening this! There's definitely space to add an extensibility interface to typage.

At first look, a Plugin interface feels like one abstraction too many: the plugin protocol is a way to extend the CLI (or other applications) with code that lives in other binaries. When the code is available as a Go library, it can just be exposed as a Recipient and/or Identity implementation. (Note how even a plugin client is then exposed as Recipient/Identity in the Go library, the core age Go library has no concept of plugins.)

Couldn't we just define equivalent Recipient and Identity TypeScript interfaces, and then accept them from addIdentity and addRecipient?

[olastor]

Couldn't we just define equivalent Recipient and Identity TypeScript interfaces, and then accept them from addIdentity and addRecipient?

@FiloSottile Yeah that sounds like it would be simpler and more in line with the Go lib. Iirc I went for the rather complex interface because I wanted to pass the recipient/identity as a string or didn't want to change the function signature of addRecipient / addIdentity. For a browser environment, there is no binary that can be called, so passing an encoded plugin recipient to addRecipient() does not work unless the plugin is first "registered" somehow. If plugin string recipients would not be supported in the browser, then it might be good if the decoding step is somehow still handled by typage so that browser plugins don't need to always have bech32 as an additional dependency in order to implement a parsing function that converts a recipient from string into an Recipient type.

[FiloSottile]

If plugin string recipients would not be supported in the browser, then it might be good if the decoding step is somehow still handled by typage so that browser plugins don't need to always have bech32 as an additional dependency in order to implement a parsing function that converts a recipient from string into an Recipient type.

Yeah it would make sense to expose the equivalents of the https://pkg.go.dev/filippo.io/age/plugin Parse and Encode functions.