commit ec97682146488facba77bbe8da94f16a8ac2b1b6
parent 28a0f2b0af54d9d64a6d0f3c6610ba4f3d40423b
Author: triesap <tyson@radroots.org>
Date: Wed, 7 Oct 2026 04:55:59 +0000
messages: restrict protocol-generated wrapper keys (HCP-059)
- Introduce an opaque outer1059 construction permission for genuine private sessions.
- Restrict the SDK-derived outer template type without exposing signer or key APIs.
- Fence acquisition and retained ownership across logout and account changes.
- Verify initial custody boundaries while retaining later wrapper construction ownership.
Diffstat:
3 files changed, 262 insertions(+), 0 deletions(-)
diff --git a/web/src/lib/nostr/private-envelope-capability.ts b/web/src/lib/nostr/private-envelope-capability.ts
@@ -0,0 +1,99 @@
+import type { EventTemplate } from 'applesauce-core/helpers/event';
+import {
+ privateSessionOwnership,
+ subscribePrivateSessionClose,
+ type PrivateSession
+} from '../runtime/private-session.ts';
+import type { PublicEffectCapture } from '../runtime/effect-ownership.ts';
+
+// Internal construction shape only, not a validated seal/recipient plan. Later
+// preparation must establish the peer or self-copy target and authentic seal.
+export type PrivateOuterTemplate = Readonly<{
+ kind: 1059;
+ tags: readonly [readonly ['p', string]];
+ content: EventTemplate['content'];
+ created_at: EventTemplate['created_at'];
+}>;
+declare const envelopeBrand: unique symbol;
+export type PrivateEnvelopeCapability = Readonly<{
+ [envelopeBrand]: PrivateOuterTemplate;
+}>;
+type ConstructionOwnership = Readonly<PublicEffectCapture & { kind: 1059 }>;
+type Controller = {
+ ownership(): ConstructionOwnership | undefined;
+ close(): void;
+};
+const capabilities = new WeakMap<PrivateEnvelopeCapability, Controller>();
+const sessions = new WeakMap<PrivateSession, PrivateEnvelopeCapability>();
+
+// Executable initial permission boundary, deliberately unused by product sends
+// until HCM015. No signer is created, passed in or exposed, and no identity key
+// or raw key API exists. Later Applesauce disposable-key use stays wholly inside
+// the outer construction adapter; this token cannot sign a listing or decrypt.
+export function getPrivateEnvelopeCapability(
+ session: PrivateSession
+): PrivateEnvelopeCapability | undefined {
+ if (typeof window === 'undefined') return undefined;
+ const observed = privateSessionOwnership(session);
+ if (!observed) throw new Error('private_session_invalid');
+ const capture = observed;
+ const prior = sessions.get(session);
+ if (prior) {
+ if (!controller(prior).ownership())
+ throw new Error('private_envelope_capability_closed');
+ return prior;
+ }
+ const token = Object.freeze({}) as PrivateEnvelopeCapability;
+ let closed = false;
+ let off = () => {};
+ function close() {
+ if (closed) return;
+ closed = true;
+ off();
+ capabilities.set(token, {
+ ownership: () => undefined,
+ close: () => {}
+ });
+ }
+ function current() {
+ if (closed || !capture.current()) {
+ close();
+ return false;
+ }
+ return true;
+ }
+ capabilities.set(token, {
+ ownership: () =>
+ current()
+ ? {
+ kind: 1059,
+ owner: capture.owner,
+ session: capture.session,
+ current
+ }
+ : undefined,
+ close
+ });
+ off = subscribePrivateSessionClose(session, close);
+ if (!current()) {
+ close();
+ return undefined;
+ }
+ sessions.set(session, token);
+ return token;
+}
+function controller(token: PrivateEnvelopeCapability): Controller {
+ const state = capabilities.get(token);
+ if (!state) throw new Error('private_envelope_capability_invalid');
+ return state;
+}
+export function privateEnvelopeConstructionOwnership(
+ token: PrivateEnvelopeCapability
+): ConstructionOwnership | undefined {
+ return controller(token).ownership();
+}
+export function closePrivateEnvelopeCapability(
+ token: PrivateEnvelopeCapability
+): void {
+ controller(token).close();
+}
diff --git a/web/tests/integration/private-envelope-capability.test.ts b/web/tests/integration/private-envelope-capability.test.ts
@@ -0,0 +1,130 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as boundary from '../../src/lib/nostr/private-envelope-capability.ts';
+import {
+ createIdentitySession,
+ connectIdentity,
+ probeIdentityMessaging,
+ disconnectIdentity,
+ recheckIdentityOwner
+} from '../../src/lib/runtime/identity-session.ts';
+import { createPrivateSession } from '../../src/lib/runtime/private-session.ts';
+
+// HC_TEST_ONLY_PROVIDER: actual SDK ownership; echo is not encryption qualification.
+await test('outer-only construction permission follows actual SDK private-session generations without creating keys', async () => {
+ const owner =
+ '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798';
+ const other =
+ 'c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5';
+ assert.equal(typeof window, 'undefined');
+ assert.equal(boundary.getPrivateEnvelopeCapability({} as never), undefined);
+ let key = owner,
+ prompts = 0,
+ signatures = 0;
+ Object.defineProperty(globalThis, 'window', {
+ configurable: true,
+ value: {
+ nostr: {
+ getPublicKey: () => {
+ prompts++;
+ return Promise.resolve(key);
+ },
+ signEvent: () => {
+ signatures++;
+ return Promise.reject(new Error('HC_TEST_ONLY_UNEXPECTED_SIGN'));
+ },
+ nip44: {
+ encrypt: (_peer: string, text: string) =>
+ Promise.resolve('fixture:' + text),
+ decrypt: (_peer: string, text: string) =>
+ Promise.resolve(text.slice(8))
+ }
+ }
+ }
+ });
+ const identity = createIdentitySession();
+ async function connect() {
+ assert.equal((await connectIdentity(identity)).state, 'signing_only');
+ assert.equal(
+ (await probeIdentityMessaging(identity, 'reviewed_self_copy')).state,
+ 'messaging_capable'
+ );
+ const session = await createPrivateSession(
+ identity,
+ 'reviewed_private_session'
+ );
+ assert.ok(session);
+ return session;
+ }
+ try {
+ assert.throws(
+ () => boundary.getPrivateEnvelopeCapability({} as never),
+ /private_session_invalid/
+ );
+ assert.throws(
+ () => boundary.getPrivateEnvelopeCapability(identity as never),
+ /private_session_invalid/
+ );
+ assert.equal(prompts, 0);
+ const session = await connect();
+ const before = prompts;
+ const token = boundary.getPrivateEnvelopeCapability(session);
+ assert.ok(token);
+ assert.equal(boundary.getPrivateEnvelopeCapability(session), token);
+ assert.deepEqual(Reflect.ownKeys(token), []);
+ const captured = boundary.privateEnvelopeConstructionOwnership(token);
+ assert.ok(captured);
+ assert.equal(captured.kind, 1059);
+ assert.equal(captured.owner, owner);
+ assert.equal(captured.current(), true);
+ assert.deepEqual(Object.keys(captured).sort(), [
+ 'current',
+ 'kind',
+ 'owner',
+ 'session'
+ ]);
+ assert.equal(prompts, before);
+ assert.equal(signatures, 0);
+ disconnectIdentity(identity);
+ assert.equal(captured.current(), false);
+ assert.equal(
+ boundary.privateEnvelopeConstructionOwnership(token),
+ undefined
+ );
+ const again = boundary.getPrivateEnvelopeCapability(await connect());
+ assert.ok(again);
+ assert.notEqual(again, token);
+ assert.equal(
+ boundary.privateEnvelopeConstructionOwnership(token),
+ undefined
+ );
+ key = other;
+ assert.equal((await recheckIdentityOwner(identity)).state, 'guest');
+ assert.equal(
+ boundary.privateEnvelopeConstructionOwnership(again),
+ undefined
+ );
+ const replacementSession = await connect();
+ const replacement =
+ boundary.getPrivateEnvelopeCapability(replacementSession);
+ assert.ok(replacement);
+ assert.equal(
+ boundary.privateEnvelopeConstructionOwnership(replacement)?.owner,
+ other
+ );
+ boundary.closePrivateEnvelopeCapability(replacement);
+ boundary.closePrivateEnvelopeCapability(replacement);
+ assert.equal(
+ boundary.privateEnvelopeConstructionOwnership(replacement),
+ undefined
+ );
+ assert.throws(
+ () => boundary.getPrivateEnvelopeCapability(replacementSession),
+ /private_envelope_capability_closed/
+ );
+ assert.equal(signatures, 0);
+ } finally {
+ disconnectIdentity(identity);
+ Reflect.deleteProperty(globalThis, 'window');
+ }
+});
diff --git a/web/tests/unit/private-boundary.test.ts b/web/tests/unit/private-boundary.test.ts
@@ -0,0 +1,33 @@
+import { expect, expectTypeOf, it } from 'vitest';
+import * as boundary from '../../src/lib/nostr/private-envelope-capability.ts';
+import type {
+ PrivateEnvelopeCapability,
+ PrivateOuterTemplate
+} from '../../src/lib/nostr/private-envelope-capability.ts';
+
+it('outer construction permission is SSR inert and exposes no signer or credential API', () => {
+ expect(boundary.getPrivateEnvelopeCapability({} as never)).toBeUndefined();
+ expect(Object.keys(boundary).sort()).toEqual([
+ 'closePrivateEnvelopeCapability',
+ 'getPrivateEnvelopeCapability',
+ 'privateEnvelopeConstructionOwnership'
+ ]);
+ expectTypeOf<PrivateOuterTemplate['kind']>().toEqualTypeOf<1059>();
+ expectTypeOf<PrivateOuterTemplate['tags']>().toEqualTypeOf<
+ readonly [readonly ['p', string]]
+ >();
+ expectTypeOf<
+ Extract<
+ keyof PrivateEnvelopeCapability,
+ 'signEvent' | 'key' | 'nip44' | 'exportKey' | 'importKey'
+ >
+ >().toEqualTypeOf<never>();
+});
+it('forged outer capability cannot authorize signing, acquire ownership or close a scope', () => {
+ expect(() =>
+ boundary.privateEnvelopeConstructionOwnership({} as never)
+ ).toThrow('private_envelope_capability_invalid');
+ expect(() => boundary.closePrivateEnvelopeCapability({} as never)).toThrow(
+ 'private_envelope_capability_invalid'
+ );
+});