@synonymdev/pubky 0.17.1 → 0.18.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Decentralized identity, auth flows, and user-owned storage",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -41,7 +41,7 @@
     "@types/tape": "^5.6.4",
     "browser-resolve": "^2.0.0",
     "browserify": "^17.0.1",
-    "electron": "41.0.2",
+    "electron": "45.1.0",
     "esmify": "^2.1.1",
     "tape": "^5.8.1",
     "tape-run": "^11.0.0",
@@ -52,6 +52,7 @@
     "fetch-cookie": "^3.0.1"
   },
   "overrides": {
-    "electron": "41.0.2"
+    "electron": "45.1.0",
+    "minimist": "^1.2.8"
   }
 }

package/pubky.d.ts

@@ -25,6 +25,33 @@ export interface RecoveredEncryptionKeys {
 
 
 
+/** The individual limits of a quota. A limit is a number, a rate string such as
+ * `"100mb/m"`, or `"unlimited"`. Absent in `overrides` means the system default. */
+export interface AccountQuotaLimits {
+    /** Storage quota in megabytes, or "unlimited". */
+    storageQuotaMb?: number | "unlimited";
+    /** Read bandwidth limit, e.g. "100mb/m", or "unlimited". */
+    rateRead?: string;
+    /** Write bandwidth limit, e.g. "50mb/s", or "unlimited". */
+    rateWrite?: string;
+    /** Burst allowance for reads, in the rate's unit. Absent means burst equals rate. */
+    rateReadBurst?: number;
+    /** Burst allowance for writes, in the rate's unit. Absent means burst equals rate. */
+    rateWriteBurst?: number;
+    /** Path prefixes the user may write to. Absent means unrestricted; empty means read-only. */
+    allowedWritePaths?: string[];
+}
+
+/** A user's quota, both as it applies and as it was customised. */
+export interface AccountQuota {
+    /** Overrides merged with the homeserver's defaults. */
+    effective: AccountQuotaLimits;
+    /** Only the per-user overrides. */
+    overrides: AccountQuotaLimits;
+}
+
+
+
 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 {
@@ -96,6 +123,15 @@ export interface GrantAuthFlowOptions {
      * `signedApprovalV1` sets `af=v1` in the authorization link.
      */
     approvalFormat?: GrantApprovalFormat;
+    /**
+     * Optional expected identity: public key of the signed-in user that must
+     * approve, as raw z32 or `pubky<z32>`. Set it only when the app already
+     * knows the user, e.g. to re-authorize or request more capabilities. It
+     * adds `spk` to the link; signers approve with that key or refuse, and the
+     * flow rejects approvals from any other key. Switching accounts takes a
+     * flow without it. Sign-up flows reject it.
+     */
+    expectedSigner?: string | null;
 }
 
 /**
@@ -180,6 +216,7 @@ export type RequestErrorReason =
 | "Http"
 | "Timeout"
 | "Connection"
+| "TlsVerification"
 | "Body"
 | "Decode"
 | "InvalidRequest"
@@ -319,6 +356,39 @@ export type Capabilities = "" | CapabilityEntry | `${CapabilityEntry}${Capabilit
 export type Path = `/pub/${string}` | `/priv/${string}`;
 
 
+/**
+ * A user's account as returned by `session.grant.account()`.
+ */
+export class AccountInfo {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * When the user signed up, as an ISO 8601 date and time without a UTC
+     * offset (e.g. `2026-10-22T10:11:12.123456`).
+     */
+    readonly createdAt: string;
+    /**
+     * Whether the account is disabled. Disabled accounts can read and delete
+     * but not write.
+     */
+    readonly disabled: boolean;
+    /**
+     * The user this account belongs to.
+     */
+    readonly pubky: PublicKey;
+    /**
+     * The quota that applies and the per-user overrides behind it.
+     *
+     * @returns {AccountQuota}
+     */
+    readonly quota: AccountQuota;
+    /**
+     * Bytes of storage currently used.
+     */
+    readonly usedBytes: number;
+}
+
 /**
  * Start and control a pubkyauth authorization flow.
  *
@@ -1069,7 +1139,7 @@ export class GrantAuthFlow {
      * The kind of authentication flow to perform.
      *
      * @param {GrantAuthFlowOptions} options
-     * Options for the grant flow: `{ clientId, relay?, xCallback? }`.
+     * Options for the grant flow: `{ clientId, relay?, xCallback?, approvalFormat?, expectedSigner? }`.
      *
      * @returns {GrantAuthFlow}
      * A running grant auth flow. Call `authorizationUrl()` to show the deep link,
@@ -1169,6 +1239,17 @@ export class GrantSession {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Fetch this user's account: storage used, whether it is disabled, and
+     * the quota that applies.
+     *
+     * Requires read permission on the root scope (`/:r`, `/:rw`, ...).
+     * Path-scoped sessions surface the homeserver `403` as the standard
+     * request error.
+     *
+     * @returns {Promise<AccountInfo>}
+     */
+    account(): Promise<AccountInfo>;
     /**
      * 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.
@@ -1611,7 +1692,7 @@ export class Pubky {
      * @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?, approvalFormat? }`.
+     * `{ clientId, relay?, xCallback?, approvalFormat?, expectedSigner? }`.
      * @returns {Promise<GrantAuthFlow>}
      * A running grant auth flow. Show `authorizationUrl` as QR/deeplink,
      * then `awaitApproval()` to obtain a grant-backed `Session`.
@@ -1712,7 +1793,8 @@ export class PubkyResource {
      */
     static parse(value: string): PubkyResource;
     /**
-     * Render as `pubky://<owner>/<path>` (deep-link/URL form).
+     * Render as `pubky://<owner><path>` (deep-link form), the form listings
+     * and events use.
      */
     toPubkyUrl(): string;
     /**
@@ -1724,7 +1806,7 @@ export class PubkyResource {
      */
     readonly owner: PublicKey;
     /**
-     * Get the absolute path (e.g., "/pub/example.txt").
+     * Get the absolute path (e.g., "/pub/My File.txt").
      */
     readonly path: string;
 }
@@ -1794,10 +1876,10 @@ export class PublicStorage {
      */
     get(address: Address): Promise<Response>;
     /**
-     * List a directory. Results are `pubky://…` identifier URLs.
+     * List a directory. Results are `pubky://<pk><path>` entries.
      *
      * @param {Address} address Addressed directory (must end with `/`).
-     * @param {string|null=} cursor Optional suffix or full URL to start **after**.
+     * @param {string|null=} cursor Optional suffix or entry (as returned) to start **after**.
      * @param {boolean=} reverse Default `false`. When `true`, newest/lexicographically-last first.
      * @param {number=} limit Optional result limit.
      * @param {boolean=} shallow Default `false`. When `true`, lists only first-level entries.
@@ -2034,11 +2116,11 @@ export class SessionStorage {
      * List a directory (absolute session path).
      *
      * @param {Path} path Must end with `/`.
-     * @param {string|null=} cursor Optional last entry URL to start **after**.
+     * @param {string|null=} cursor Optional last entry (as returned) to start **after**.
      * @param {boolean=} reverse Default `false`.
      * @param {number=} limit Optional result limit.
      * @param {boolean=} shallow Default `false`.
-     * @returns {Promise<string[]>} `pubky://…` entry URLs, or an empty array for an empty page.
+     * @returns {Promise<string[]>} `pubky://<pk><path>` entries, or an empty array for an empty page.
      * @throws {PubkyError} Missing directory (404), invalid cursor (400), invalid response
      * entries, or shared errors (see {@link SessionStorage}).
      */
@@ -2374,6 +2456,13 @@ export class SigninGrantDeepLink {
      * @returns {Uint8Array|undefined}
      */
     readonly ephemeralPublicKey: Uint8Array | undefined;
+    /**
+     * Expected identity (`spk`): the public key that must approve this
+     * request, or `undefined`. Signers approve with this key or refuse.
+     *
+     * @returns {PublicKey|undefined}
+     */
+    readonly expectedSigner: PublicKey | undefined;
     /**
      * Shared relay secret, or `undefined` for an HPKE link.
      * Keep this secret confidential until the flow completes or is abandoned.