@punica/editor 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

package/types/punica.module.kernel.policy.d.ts

@@ -266,6 +266,48 @@ declare module 'punica' {
       approvals: ApprovalRecord[];
     }
 
+    /**
+     * A signed approval grant. The gate matches a grant by (kind, id) plus
+     * scope and workspace; the token is what lets a later reader prove the
+     * grant was really issued and not edited afterwards.
+     */
+    export interface ApprovalTokenPayload {
+      scope: ApprovalScope;
+      capabilityId: string;
+      expiry: number;
+      jti: string;
+      issuer: string;
+      workspaceId?: string;
+      delegatedFrom?: string;
+      delegationDepth?: number;
+      approval?: PolicyApproval;
+      risk?: PolicyRisk;
+    }
+
+    /**
+     * Signs approval grants. The substrate default is HMAC-SHA256 over an
+     * in-memory ephemeral key, which does not survive a restart; a
+     * production host injects its own through
+     * `punica.runtime.setApprovalTokenSigner`.
+     */
+    export interface ApprovalTokenSigner {
+      /** Sign `payload`; returns the compact token string. */
+      sign(payload: ApprovalTokenPayload): Promise<string>;
+    }
+
+    /** Verifies (and revokes) approval tokens. */
+    export interface ApprovalTokenVerifier {
+      /**
+       * Parse, check the header and signature, check expiry and jti
+       * revocation. Returns the payload, or throws with a stable code.
+       */
+      verify(token: string): Promise<ApprovalTokenPayload>;
+      /** Mark a jti revoked; tokens carrying it then fail verification. */
+      revoke(jti: string): void;
+      /** Is a jti currently revoked? */
+      isRevoked(jti: string): boolean;
+    }
+
     export namespace Policy {
       const manager: PolicyApi;
     }

package/types/punica.module.runtime.api.d.ts

@@ -187,7 +187,50 @@ declare module 'punica' {
       setResourcesProvider: (provider: ResourcesApi) => void;
       setTasksProvider: (provider: TaskRunnerApi) => void;
       setSecretsProvider: (provider: SecretsApi) => void;
+
+      /**
+       * Approval-token signing. The substrate default mints an in-memory
+       * ephemeral HMAC key on the first signature and loses it when the
+       * process exits, so a token signed before a restart no longer
+       * verifies after one — fine for dev and demo, useless as evidence.
+       * A production host installs a stable secret from the OS keychain
+       * during bootstrap, before `initialize()`:
+       *
+       *   punica.runtime.installDefaultApprovalTokenPair(secret)
+       *
+       * The two setters are the same seam for a host that brings its own
+       * signer (KMS, HSM); passing `undefined` restores the substrate
+       * default. The key belongs to the host and never to an extension —
+       * an extension that can reach the signing key can also produce the
+       * thing it signs.
+       */
+      installDefaultApprovalTokenPair: (secret: Uint8Array | string) => void;
+      setApprovalTokenSigner: (
+        signer: kernel.ApprovalTokenSigner | undefined
+      ) => void;
+      setApprovalTokenVerifier: (
+        verifier: kernel.ApprovalTokenVerifier | undefined
+      ) => void;
+
+      /**
+       * Who is at this workstation, so a user-initiated call's audit record
+       * names a subject instead of leaving `actor.id` empty. Absent is a
+       * normal state — a trial licence has no account — and the substrate
+       * invents nothing to fill it. Passing `undefined` clears it.
+       */
+      setHostIdentity: (identity: HostIdentity | undefined) => void;
     }
+
+    /**
+     * The person a licence belongs to, as the host knows them. `email` is
+     * the identifier (a registry guarantees it unique and present);
+     * `displayName` is presentation and may be absent.
+     */
+    export interface HostIdentity {
+      email: string;
+      displayName?: string | null;
+    }
+
   }
 
   export const runtime: runtime.RuntimeApi;