@synonymdev/pubky 0.15.0 → 0.16.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Decentralized identity, auth flows, and user-owned storage",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "testnet": "cargo run -p pubky-testnet",
-    "build:test": "tsc --project tsconfig.json && mkdir -p dist && cp index.js dist/index.js",
+    "build:test": "rm -rf dist/tests && tsc --project tsconfig.json && mkdir -p dist && cp index.js dist/index.js",
     "test": "npm run test-nodejs && npm run test-browser",
     "test-nodejs": "npm run build:test && node --require ./node-header.cjs node_modules/tape/bin/tape dist/tests/*.js -cov",
     "test-browser": "npm run build:test && browserify dist/tests/setup.js dist/tests/*.js -p esmify | npx tape-run",

package/pubky.d.ts

@@ -12,6 +12,32 @@ export type Level = "error" | "warn" | "info" | "debug" | "trace";
  */
 
 export type ReadableStreamType = "bytes";
+
+/** Offline recovery result. Check the identity before using the keys. */
+export interface RecoveredEncryptionKeys {
+    /** Authenticated account public key, encoded as z-base-32. */
+    publicKey: string;
+    /** Authenticated grant identifier (jti). */
+    grantId: string;
+    /** Independently owned scoped keys. Call keys.free() when finished. */
+    keys: EncryptionKeys;
+}
+
+
+
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+/** Root-signed grant claims. Public keys are z-base-32; times are Unix seconds. */
+export interface VerifiedGrantClaims {
+    iss: string;
+    client_id: string;
+    caps: string[];
+    cnf: string;
+    jti: string;
+    iat: number;
+    exp: number;
+}
+
+
 /**
  * A union type of all possible machine-readable codes for the `name` property
  * of a {@link PubkyError}.
@@ -63,6 +89,25 @@ export interface GrantAuthFlowOptions {
      * Optional return destinations for success, error, and cancellation.
      */
     xCallback?: XCallbackParams | null;
+    /**
+     * Relay approval format. `signedApprovalV1` delivers keys for approved `e` scopes
+     * and rejects bare-grant downgrades.
+     * Omitted or `bareGrant` selects a grant without an approval envelope.
+     * `signedApprovalV1` sets `af=v1` in the authorization link.
+     */
+    approvalFormat?: GrantApprovalFormat;
+}
+
+/**
+ * Options for verifying custom grant proofs.
+ */
+export interface CustomPopVerificationOptions {
+    /**
+     * Allow the grant's issue time this many seconds ahead of the local clock.
+     * Defaults to 30; zero disables the allowance. Expiry remains strict.
+     * Must be an integer between 0 and 4294967295.
+     */
+    clockSkewSeconds?: number;
 }
 
 /**
@@ -96,6 +141,11 @@ export interface PubkyClientConfig {
     maxErrorBodyBytes?: number;
 }
 
+/**
+ * Relay payload format understood by the requesting app.
+ */
+export type GrantApprovalFormat = "bareGrant" | "signedApprovalV1";
+
 /**
  * Represents the standard error structure for all exceptions thrown by the Pubky
  * WASM client.
@@ -202,9 +252,50 @@ export interface ResourceStats {
     etag?: string;
 }
 
+/**
+ * Self-contained credentials for offline custom-proof verification.
+ * Unknown fields are ignored so future bundles remain readable by older verifiers.
+ */
+export interface CustomPop {
+    /**
+     * Original root-signed grant JWS.
+     */
+    grant: string;
+    /**
+     * Client-signed custom proof JWS.
+     */
+    pop: string;
+}
+
+/**
+ * Verified provenance and data; applications validate the data's meaning.
+ */
+export interface VerifiedCustomPop {
+    /**
+     * Root public key encoded as z-base-32.
+     */
+    identity: string;
+    /**
+     * Root-signed claims; storage capabilities do not grant service permissions.
+     */
+    grantClaims: VerifiedGrantClaims;
+    /**
+     * Unix seconds at which the client signed the proof. No maximum age is enforced.
+     */
+    iat: number;
+    /**
+     * Random per-proof value. Record it until grant expiry to detect replays.
+     */
+    nonce: string;
+    /**
+     * Signed JSON data, without application-specific validation.
+     */
+    data: JsonValue;
+}
+
 export type Address = `pubky${string}/pub/${string}` | `pubky://${string}/pub/${string}`;
 
-export type CapabilityAction = "r" | "w" | "rw";
+export type CapabilityAction = "r" | "w" | "e" | "rw" | "re" | "we" | "rwe";
 export type CapabilityScope = `/${string}`;
 export type CapabilityEntry = `${CapabilityScope}:${CapabilityAction}`;
 type CapabilitiesTail = `,${CapabilityEntry}${string}`;
@@ -481,6 +572,16 @@ export class BrowserSessionStore {
      * Remove local stored session metadata and any SDK-owned delegated key for that record.
      */
     remove(id: string): Promise<void>;
+    /**
+     * Recover a stored session's encryption keys without network access.
+     * Verifies the signed approval, exact grant binding, and requested session
+     * identity. Works after grant expiry/revocation and without the delegated
+     * WebCrypto signing key.
+     * Restore material is stored as plaintext in IndexedDB.
+     * Bare-grant records return undefined; signed approvals without `e` scopes
+     * return an empty bundle. Creates no session.
+     */
+    restoreEncryptionKeys(id: string): Promise<EncryptionKeys | undefined>;
     /**
      * Restore a specific stored session by id.
      *
@@ -489,7 +590,11 @@ export class BrowserSessionStore {
      */
     restore(id: string): Promise<Session>;
     /**
-     * Persist a completed grant session in IndexedDB.
+     * Persist a completed grant session and its optional signed approval.
+     * Confidential restore material is stored as plaintext in IndexedDB.
+     * Delegated signing keys remain non-extractable WebCrypto keys.
+     * Records are identified by user and grant ID. Reauthorizing the same
+     * client creates a separate record; use the returned ID to restore it.
      */
     save(session: Session): Promise<StoredSessionInfo>;
 }
@@ -617,6 +722,42 @@ export class DirectSignupDeepLink {
     readonly xCallback: XCallbackParams;
 }
 
+/**
+ * Verified scoped encryption keys obtained from a session or offline recovery.
+ * This object owns its secrets independently of the session and grants no storage
+ * access. Call `free()` when finished; secret bytes are zeroized on free/drop.
+ */
+export class EncryptionKeys {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Derive a non-extractable AES-GCM-256 key for WebCrypto encryption/decryption.
+     * Rejects directories and files outside approved scopes. Requires WebCrypto.
+     * Temporary JS key bytes are cleared after import, including on failure.
+     */
+    deriveCryptoKeyForPath(path: string): Promise<CryptoKey>;
+    /**
+     * Derive a 32-byte content key for a canonical decoded file path.
+     * Rejects directories and files outside the approved scopes. The caller
+     * owns the JS byte copy and should clear it after use.
+     */
+    deriveForPath(path: string): Uint8Array;
+    /**
+     * Recover authenticated identity and keys from an exportLocalSecret() token offline.
+     * Verifies the signed approval and grant binding even if the grant expired
+     * or was revoked. Bare-grant tokens return undefined; signed approvals
+     * without `e` scopes return a result with an empty key bundle.
+     * Check publicKey (z-base-32) against the expected account and grantId
+     * against the expected grant before using keys. Call keys.free() when done.
+     */
+    static fromLocalSecret(token: string): RecoveredEncryptionKeys | undefined;
+    /**
+     * Approved scopes; directory scopes cover descendant files.
+     */
+    readonly scopes: string[];
+}
+
 /**
  * A single event from the event stream.
  *
@@ -867,7 +1008,8 @@ export class GrantAuthFlow {
      * Resume a previously saved pending grant auth flow (standalone).
      * Prefer `pubky.resumeGrantAuthFlow()` to reuse a facade client.
      *
-     * **Security:** `savedState` contains the relay secret and PoP client private key.
+     * **Security:** `savedState` contains the PoP client private key and either
+     * a shared relay secret or a temporary HPKE recipient secret.
      * Store it only temporarily and delete it once the flow completes or is abandoned.
      *
      * @param {string} savedState A string produced by `grantFlow.saveLocal()`.
@@ -877,9 +1019,9 @@ export class GrantAuthFlow {
     /**
      * Save sensitive state required to resume this delegated pending grant flow.
      *
-     * This does not export the delegated private key, but it includes the relay
-     * secret in the authorization URL. Store it only temporarily and delete it
-     * once the flow completes or is abandoned.
+     * This includes either a shared relay secret or a temporary HPKE recipient
+     * secret. Store it only temporarily and delete it once the flow completes
+     * or is abandoned.
      */
     saveDelegated(): string;
     /**
@@ -1012,11 +1154,19 @@ export class GrantSession {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Sign JSON data and return both the custom proof and its root-signed grant.
+     * Data follows `JSON.stringify` semantics, e.g. `undefined` properties are omitted.
+     * Each proof carries its signing time (`iat`) and a random `nonce`.
+     * Makes no network requests. Your applications handle freshness and replay protection.
+     */
+    createCustomPop(data: JsonValue): Promise<CustomPop>;
     /**
      * Export the portable local secret material needed to restore this grant session.
      *
      * Treat the returned string as bearer-equivalent secret material until the
-     * grant expires or is revoked.
+     * grant expires or is revoked. Included scoped keys remain sensitive after
+     * expiry or revocation.
      *
      * @returns {Promise<string>}
      */
@@ -1033,6 +1183,15 @@ export class GrantSession {
      * @returns {Promise<GrantSessionInfo>}
      */
     sessionInfo(): Promise<GrantSessionInfo>;
+    /**
+     * Return scoped keys with the same derivation API as offline recovered keys.
+     * Bare grants return `undefined`; signed approvals without `e` scopes
+     * return an object with empty scopes.
+     * Each access creates an owned copy. Keep it for repeated use and call
+     * `free()` when finished. It remains usable after this view or its session
+     * is freed, signed out, or revoked; freeing it does not affect the session.
+     */
+    readonly encryptionKeys: EncryptionKeys | undefined;
 }
 
 /**
@@ -1370,8 +1529,9 @@ export class Pubky {
     /**
      * Resume a previously saved pending grant auth flow.
      *
-     * **Security:** `savedState` contains the relay secret and PoP client private key.
-     * Delete it from storage as soon as the resumed flow completes.
+     * **Security:** `savedState` contains the PoP client private key and either
+     * a shared relay secret or a temporary HPKE private key. Delete it from
+     * storage when the flow completes or is abandoned.
      *
      * @param {string} savedState A string produced by `grantFlow.saveLocal()`.
      * @returns {GrantAuthFlow} A flow reconnected to the original relay channel.
@@ -1430,11 +1590,13 @@ export class Pubky {
      *
      * Grant auth uses a user-signed grant JWS plus Proof-of-Possession and
      * returns a self-refreshing session.
+     * Select `approvalFormat: "signedApprovalV1"` and include `e` on scopes that need content
+     * keys. Storage `r` and `w` alone do not deliver encryption keys.
      *
      * @param {string} capabilities Comma-separated caps, e.g. `"/pub/app/:rw,/pub/foo/file:r"`.
      * @param {AuthFlowKind} kind The kind of authentication flow to perform.
      * @param {GrantAuthFlowOptions} options Options for the grant flow:
-     * `{ clientId, relay?, xCallback? }`.
+     * `{ clientId, relay?, xCallback?, approvalFormat? }`.
      * @returns {Promise<GrantAuthFlow>}
      * A running grant auth flow. Show `authorizationUrl` as QR/deeplink,
      * then `awaitApproval()` to obtain a grant-backed `Session`.
@@ -2001,7 +2163,8 @@ export class Signer {
     /**
      * Blocking sign-in. Waits for PKDNS publish to complete (slower; safer).
      *
-     * Creates a valid grant-backed homeserver Session with root capabilities.
+     * Creates a grant-backed homeserver session with root storage access (`/:rw`).
+     * Encryption keys require an explicit `e` request through a signed approval flow.
      * `clientId` is shown in the user's grant/session list.
      * @param {string} clientId App identifier, typically a domain.
      *
@@ -2023,7 +2186,8 @@ export class Signer {
     /**
      * Fast sign-in for a returning user. Publishes PKDNS in the background.
      *
-     * Creates a valid grant-backed homeserver Session with root capabilities.
+     * Creates a grant-backed homeserver session with root storage access (`/:rw`).
+     * Encryption keys require an explicit `e` request through a signed approval flow.
      * `clientId` is shown in the user's grant/session list.
      * @param {string} clientId App identifier, typically a domain.
      *
@@ -2108,6 +2272,10 @@ export class SigninGrantDeepLink {
      * @returns {string}
      */
     toString(): string;
+    /**
+     * Negotiated approval format: `bareGrant` or `signedApprovalV1`.
+     */
+    readonly approvalFormat: string;
     /**
      * Base HTTP relay inbox URL used by this auth request.
      *
@@ -2133,13 +2301,21 @@ export class SigninGrantDeepLink {
      */
     readonly clientPublicKey: PublicKey;
     /**
-     * Relay channel secret embedded in the deeplink.
+     * The 32-byte ephemeral HPKE public key from `epk`, or `undefined`
+     * for a shared-secret link. The relay channel ID is the unpadded
+     * base64url encoding of BLAKE3("pubky-grant-relay-channel-v1" || 0x00 || epk),
+     * where `||` concatenates bytes and `epk` is the raw 32-byte public key.
      *
-     * Treat this as sensitive temporary auth-flow material.
+     * @returns {Uint8Array|undefined}
+     */
+    readonly ephemeralPublicKey: Uint8Array | undefined;
+    /**
+     * Shared relay secret, or `undefined` for an HPKE link.
+     * Keep this secret confidential until the flow completes or is abandoned.
      *
-     * @returns {Uint8Array}
+     * @returns {Uint8Array|undefined}
      */
-    readonly secret: Uint8Array;
+    readonly secret: Uint8Array | undefined;
     /**
      * Optional x-callback-url metadata carried by this deep link.
      */
@@ -2187,6 +2363,10 @@ export class SignupGrantDeepLink {
      * @returns {string}
      */
     toString(): string;
+    /**
+     * Negotiated approval format: `bareGrant` or `signedApprovalV1`.
+     */
+    readonly approvalFormat: string;
     /**
      * Base HTTP relay inbox URL used by this auth request.
      *
@@ -2211,6 +2391,15 @@ export class SignupGrantDeepLink {
      * @returns {PublicKey}
      */
     readonly clientPublicKey: PublicKey;
+    /**
+     * The 32-byte ephemeral HPKE public key from `epk`, or `undefined`
+     * for a shared-secret link. The relay channel ID is the unpadded
+     * base64url encoding of BLAKE3("pubky-grant-relay-channel-v1" || 0x00 || epk),
+     * where `||` concatenates bytes and `epk` is the raw 32-byte public key.
+     *
+     * @returns {Uint8Array|undefined}
+     */
+    readonly ephemeralPublicKey: Uint8Array | undefined;
     /**
      * Homeserver public key requested for account creation.
      *
@@ -2218,13 +2407,12 @@ export class SignupGrantDeepLink {
      */
     readonly homeserver: PublicKey;
     /**
-     * Relay channel secret embedded in the deeplink.
-     *
-     * Treat this as sensitive temporary auth-flow material.
+     * Shared relay secret, or `undefined` for an HPKE link.
+     * Keep this secret confidential until the flow completes or is abandoned.
      *
-     * @returns {Uint8Array}
+     * @returns {Uint8Array|undefined}
      */
-    readonly secret: Uint8Array;
+    readonly secret: Uint8Array | undefined;
     /**
      * Optional signup token included in the request.
      *
@@ -2362,7 +2550,8 @@ export function setLogLevel(level: Level): void;
 /**
  * Validate and normalize a capabilities string.
  *
- * - Normalizes action order (`wr` -> `rw`)
+ * - Normalizes action order (`wr` -> `rw`, `ewr` -> `rwe`).
+ * - `e` requests scoped encryption/decryption keys in V1 grant approvals.
  * - Throws `InvalidInput` identifying the first malformed entry.
  *
  * @param {string} input
@@ -2371,3 +2560,10 @@ export function setLogLevel(level: Level): void;
  * The error's `data` field is `{ invalidEntries: string[] }` containing the malformed token.
  */
 export function validateCapabilities(input: string): string;
+
+/**
+ * Verify both signatures, grant binding, and grant validity against the local clock.
+ * Allows 30 seconds of future clock skew by default; never extends grant expiry.
+ * Does not check replay, application authorization, or homeserver revocation.
+ */
+export function verifyCustomGrantPop(credentials: CustomPop, options?: CustomPopVerificationOptions | null): VerifiedCustomPop;