@synonymdev/pubky 0.14.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.14.0",
+  "version": "0.16.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,14 +10,15 @@
   },
   "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",
     "test-browser:ci": "npm run build:test && browserify dist/tests/setup.js dist/tests/*.js -p esmify | tape-run --browser electron --electron-arg=--no-sandbox --electron-arg=--disable-gpu",
     "build": "cargo run --bin bundle_npm",
     "docs": "typedoc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test-browser:tabs": "npm run build:test && browserify dist/tests/browser/session-tabs.js -p esmify -o dist/session-tabs.bundle.js && electron scripts/session-tabs.cjs"
   },
   "files": [
     "index.cjs",
@@ -40,6 +41,7 @@
     "@types/tape": "^5.6.4",
     "browser-resolve": "^2.0.0",
     "browserify": "^17.0.1",
+    "electron": "41.0.2",
     "esmify": "^2.1.1",
     "tape": "^5.8.1",
     "tape-run": "^11.0.0",

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;
 }
 
 /**
@@ -74,8 +119,8 @@ export interface PkarrConfig {
      */
     relays?: string[];
     /**
-     * The timeout for DHT requests in milliseconds.
-     * Default is 2000ms.
+     * The timeout for relay HTTP requests in milliseconds.
+     * Default is 5000ms.
      */
     requestTimeout?: 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}`;
@@ -459,7 +550,7 @@ export class BrowserSessionStore {
      * This removes all stored session records and all browser-held delegated
      * grant keys, including keys for pending delegated grant flows. Saved
      * delegated flow state becomes unrestorable. This does not revoke remote
-     * grants or immediately invalidate already-live in-memory sessions.
+     * grants. Browser-managed handles stop working when their saved record is removed.
      */
     clearAll(): Promise<void>;
     /**
@@ -470,7 +561,7 @@ export class BrowserSessionStore {
      */
     clear(): Promise<void>;
     /**
-     * Whether IndexedDB is available for durable session persistence.
+     * Whether IndexedDB and Web Locks are available.
      */
     isAvailable(): Promise<boolean>;
     /**
@@ -481,12 +572,29 @@ 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.
+     *
+     * Shares one bearer with other tabs on this origin. Requires IndexedDB and
+     * Web Locks in a secure browser context.
      */
     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>;
 }
@@ -614,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.
  *
@@ -864,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()`.
@@ -874,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;
     /**
@@ -1009,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>}
      */
@@ -1030,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;
 }
 
 /**
@@ -1367,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.
@@ -1427,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`.
@@ -1778,12 +1943,23 @@ export class SessionInfo {
  * Only {@link SessionStorage.exists} and {@link SessionStorage.stats} treat
  * HTTP 404/410 as missing. Other HTTP failures, including 401/403 and 5xx, reject.
  * Writes require write permission and can fail on directory targets (400),
- * file/directory path conflicts (409), or exceeded quotas (507).
+ * file/directory path conflicts (409), a path someone holds a
+ * {@link StorageLock} on (423), or exceeded quotas (507).
  */
 export class SessionStorage {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * `DELETE` the path of a lock this client holds. The lock stays in place.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one.
+     * Otherwise as {@link SessionStorage.delete}.
+     */
+    deleteLocked(lock: StorageLock): Promise<void>;
     /**
      * Delete a file. Directory targets are unsupported.
      *
@@ -1850,6 +2026,35 @@ export class SessionStorage {
      * entries, or shared errors (see {@link SessionStorage}).
      */
     list(path: Path, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
+    /**
+     * Take an exclusive write lock on a file at an **absolute session path**.
+     *
+     * The file need not exist; locking a free path reserves it. `timeoutSeconds` is
+     * the lifetime asked for; the homeserver caps it, and
+     * {@link StorageLock.timeoutSeconds} tells what was granted. A write made under
+     * the lock keeps it alive until the write ends, so it need not cover the upload itself.
+     *
+     * @param {Path} path File path; must not end with `/`.
+     * @param {number} timeoutSeconds Lifetime to ask for, in seconds; rounded down to
+     * whole seconds, and at least 1.
+     * @returns {Promise<StorageLock>} The granted lock.
+     * @throws {PubkyError} `InvalidInput` for a negative, NaN or out-of-range timeout;
+     * a path that is already locked rejects with `RequestError` and status `423`;
+     * directory targets with `400`; a homeserver without lock support with `405`.
+     * See {@link SessionStorage} for shared errors.
+     */
+    lock(path: Path, timeout_seconds: number): Promise<StorageLock>;
+    /**
+     * `PUT` binary data to the path of a lock this client holds.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @param {Uint8Array} body
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one and read the file again.
+     * Otherwise as {@link SessionStorage.putBytes}.
+     */
+    putBytesLocked(lock: StorageLock, body: Uint8Array): Promise<void>;
     /**
      * Create or replace a file with binary data at an absolute session path.
      *
@@ -1869,6 +2074,17 @@ export class SessionStorage {
      * otherwise serialization, upload, or shared write/request errors (see {@link SessionStorage}).
      */
     putJson(path: Path, body: any): Promise<void>;
+    /**
+     * `PUT` text to the path of a lock this client holds.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @param {string} body
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one and read the file again.
+     * Otherwise as {@link SessionStorage.putText}.
+     */
+    putTextLocked(lock: StorageLock, body: string): Promise<void>;
     /**
      * Create or replace a file with text at an absolute session path.
      *
@@ -1878,6 +2094,22 @@ export class SessionStorage {
      * @throws {PubkyError} Upload or shared write/request errors (see {@link SessionStorage}).
      */
     putText(path: Path, body: string): Promise<void>;
+    /**
+     * Restart the lifetime of a lock this client holds.
+     *
+     * On success the lock carries the newly granted
+     * {@link StorageLock.timeoutSeconds}.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @param {number} timeoutSeconds Lifetime to ask for, in seconds; rounded down to
+     * whole seconds, and at least 1.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that has expired or was unlocked rejects with
+     * `RequestError` and status `412`; take a new one and read the file again.
+     * `InvalidInput` for a negative, NaN or out-of-range timeout.
+     * See {@link SessionStorage} for shared errors.
+     */
+    refreshLock(lock: StorageLock, timeout_seconds: number): Promise<void>;
     /**
      * Get metadata for an absolute, session-scoped path (e.g. `"/pub/app/file.json"`).
      *
@@ -1888,6 +2120,15 @@ export class SessionStorage {
      * @throws {PubkyError} All other failures (see {@link SessionStorage}).
      */
     stats(path: Path): Promise<ResourceStats | undefined>;
+    /**
+     * Release a lock this client holds.
+     *
+     * @param {StorageLock} lock A lock this client holds.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} A lock that no longer exists rejects with `RequestError`
+     * and status `409`. See {@link SessionStorage} for shared errors.
+     */
+    unlock(lock: StorageLock): Promise<void>;
 }
 
 /**
@@ -1922,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.
      *
@@ -1944,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.
      *
@@ -2029,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.
      *
@@ -2054,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.
      */
@@ -2108,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.
      *
@@ -2132,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.
      *
@@ -2139,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.
      *
@@ -2158,6 +2425,52 @@ export class SignupGrantDeepLink {
     readonly xCallback: XCallbackParams;
 }
 
+/**
+ * An exclusive write lock on one file path, granted by the homeserver.
+ *
+ * While the lock lives, only writes that present it are accepted on the path;
+ * every other write, and every other {@link SessionStorage.lock}, rejects with
+ * `423 Locked`. The lock ends when it is {@link SessionStorage.unlock | unlocked}
+ * or when its {@link StorageLock.timeoutSeconds} runs out without a
+ * {@link SessionStorage.refreshLock | refresh}, so a client that disappears never
+ * blocks a path for long.
+ *
+ * The lock is a bearer token: whoever holds this value, and may write the path,
+ * can use and release the lock.
+ *
+ * Calls that take the lock may overlap: a {@link SessionStorage.refreshLock | refresh}
+ * can run while a locked write is in flight.
+ *
+ * @example
+ * const lock = await session.storage.lock("/pub/my.app/state.json", 30);
+ * const state = await session.storage.getText(lock.path);
+ * await session.storage.putTextLocked(lock, state);
+ * await session.storage.unlock(lock);
+ */
+export class StorageLock {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Value of the `If` header that presents this lock on a write.
+     */
+    ifHeader(): string;
+    /**
+     * The locked path.
+     */
+    readonly path: Path;
+    /**
+     * Lifetime the homeserver granted at the last `lock` or `refreshLock`, in seconds,
+     * counted from when that call resolved. It may be shorter than what was asked for.
+     * It is not the time remaining: note when the call resolved to know when to refresh.
+     */
+    readonly timeoutSeconds: number;
+    /**
+     * The lock token URL, `opaquelocktoken:<uuid>`.
+     */
+    readonly token: string;
+}
+
 /**
  * Metadata for a session saved in the browser session store.
  */
@@ -2237,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
@@ -2246,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;