@punica/editor 1.19.2 → 1.20.0

package/package.json

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

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

@@ -212,6 +212,22 @@ declare module 'punica' {
         verifier: kernel.ApprovalTokenVerifier | undefined
       ) => void;
 
+      /**
+       * The signer and verifier currently in force — the injected pair, or
+       * the substrate's ephemeral default when a host installed none.
+       *
+       * Declared because the setters above do not work without them. The
+       * getter is the only reader of the module's active-signer binding, so
+       * with it unreachable the build eliminated the binding, and
+       * `setApprovalTokenSigner` compiled down to an empty function: a host
+       * could install a KMS signer and have it silently discarded, while
+       * `installDefaultApprovalTokenPair` installed only the verifier half.
+       * A seam is not reachable because a function exists; it is reachable
+       * when something published reads what it writes.
+       */
+      getApprovalTokenSigner: () => kernel.ApprovalTokenSigner;
+      getApprovalTokenVerifier: () => kernel.ApprovalTokenVerifier;
+
       /**
        * 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
@@ -219,6 +235,48 @@ declare module 'punica' {
        * invents nothing to fill it. Passing `undefined` clears it.
        */
       setHostIdentity: (identity: HostIdentity | undefined) => void;
+
+      /**
+       * Package signing. A host installs a signer during bootstrap so an
+       * evidence package can carry a signature a reader is able to check:
+       *
+       *   punica.runtime.setPackageSigner(signer)
+       *
+       * **There is no substrate default, deliberately.** The approval-token
+       * seam above ships an ephemeral fallback, and a host that forgets to
+       * inject a stable signer still gets signatures — ones that stop
+       * verifying at the next launch, silently. A signature nobody can verify
+       * is worse than none, because it reads as one. With no signer installed
+       * `signing.sign` refuses and a package states that it is unsigned.
+       *
+       * Passing `undefined` clears it. 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.
+       */
+      setPackageSigner: (signer: PackageSigner | undefined) => void;
+
+      /**
+       * Is this installation able to sign at all? Answers without provoking
+       * the refusal, so a package builder can choose between producing an
+       * unsigned package and failing.
+       */
+      hasPackageSigner: () => boolean;
+
+      /**
+       * Verify a detached package signature. **Pure** — no host seam and no
+       * private key, so a machine that never produced the package (and could
+       * not have) still answers whether the bytes were altered. That is the
+       * property the asymmetric key is bought for.
+       *
+       * Returns `false` for every negative outcome, malformed input included:
+       * "could not check" and "checked and wrong" are the same answer to a
+       * caller, and throwing would tempt a consumer into reading the first as
+       * "checked and fine".
+       */
+      verifyPackageSignature: (
+        bytes: Uint8Array,
+        signature: PackageSignature
+      ) => Promise<boolean>;
     }
 
     /**
@@ -231,6 +289,54 @@ declare module 'punica' {
       displayName?: string | null;
     }
 
+    /**
+     * A detached signature over a package's bytes.
+     *
+     * Asymmetric on purpose. The substrate's other signer — the approval
+     * token — is HMAC over a shared secret, which can only be verified by
+     * whoever holds that secret, and whoever holds it could have produced the
+     * tag themselves. A package is meant to be handed to someone else, so it
+     * is signed with a key whose public half travels inside the signature and
+     * whose private half never leaves the host.
+     *
+     * **What it proves:** integrity — these bytes are the bytes that were
+     * signed. **What it does not prove:** authenticity — nothing vouches for
+     * the public key, because the machine that produces a package is the
+     * machine that signs it. `selfSigned` carries that limit so a consumer
+     * states it rather than implying more.
+     */
+    export interface PackageSignature {
+      /** ECDSA P-256 with SHA-256. Chosen over Ed25519 for WebCrypto reach. */
+      alg: 'ES256';
+      /** The public half, so any reader can verify without a shared secret. */
+      publicKeyJwk: JsonWebKey;
+      /** SHA-256 over the JWK's canonical coordinates, base64url. */
+      keyId: string;
+      /** The detached signature, base64url. */
+      signature: string;
+      /** When it was produced, epoch ms, as the signing host saw it. */
+      signedAt: number;
+      /** Always true today; integrity verifies, authenticity does not. */
+      selfSigned: true;
+    }
+
+    /**
+     * The host-injected half of package signing. Implemented by the host, not
+     * by the substrate and never by an extension.
+     */
+    export interface PackageSigner {
+      /**
+       * Sign `bytes`. The implementation prefixes a protocol context string
+       * before the key sees them, so a signature made here cannot be replayed
+       * as one made for a different protocol.
+       */
+      sign(bytes: Uint8Array): Promise<PackageSignature>;
+      /** The public key, for a package header written before signing. */
+      publicKey(): Promise<
+        Pick<PackageSignature, 'alg' | 'publicKeyJwk' | 'keyId'>
+      >;
+    }
+
   }
 
   export const runtime: runtime.RuntimeApi;