@almadar/shell-runtime 0.1.0 → 1.0.0

package/dist/kernel/host.d.ts

@@ -1,13 +1,12 @@
-import { PageFactField, BrowserPageFacts, PersistenceAdapter, ServiceParams, EventPayload, JsonValue, UserContext, ServiceHostPorts, OnDeviceModelPorts, BrowserTabPort, EventStreamItem } from '@almadar/core';
+import { PageFactField, BrowserPageFacts, PersistenceAdapter, ServiceParams, EventPayload, JsonValue, UserContext, ServiceHostPorts, OnDeviceModelPorts, BrowserTabPort, JsonObject, EventStreamItem, HostAskCompletion } from '@almadar/core';
 import { InFlightCalls } from '../effects/in-flight-calls.js';
 import { ServiceCallContext } from '../service/service-provider.js';
 import { ProgramEffectName, ProgramEffectOutcome } from './program-effects.js';
-import { HttpPorts } from './http.js';
-import { CallSiteWire, Settled, SubstrateFailureWire, IoRequestWire, IoAnswerWire } from '@almadar/core/kernel-wire';
-import { OsHostPort, OsCompletionPort, OsCompletionEvent } from './os-port.js';
-import './beacon.js';
-import '../credentials/store.js';
-import './decode.js';
+import { SecretPorts } from './secret-ports.js';
+import { Settled, EventRequest, CallSiteWire, SubstrateFailureWire, IoRequestWire, IoAnswerWire, OsError } from '@almadar/core/kernel-wire';
+import { KernelModule } from './wire.js';
+import { OsHostPort, OsCompletionPort, OsTlsPort, OsCompletionEvent } from './os-port.js';
+import '../credentials/vault.js';
 
 /**
  * The host half of the kernel path: the I/O the kernel asks for, answered with the runtime's own
@@ -26,13 +25,90 @@ interface DeferredCallOutcome {
     payload: EventPayload | undefined;
     entityId: string | undefined;
     originClientId: string | undefined;
-    user: UserContext | undefined;
     locale: string | undefined;
 }
 interface SubstrateStreamSource {
     subscribe(message: (value: JsonValue) => void, ended: () => void): () => void;
 }
+/** The `audio/*` asks: a sound or music key, absent where the op names none (stop every sound, stop the music). */
+type HostAudioAsk = {
+    op: 'audio/play-sound';
+    key: string;
+} | {
+    op: 'audio/stop-sound';
+    key: string | undefined;
+} | {
+    op: 'audio/change-music';
+    key: string | undefined;
+} | {
+    op: 'audio/stop-music';
+};
+/** The one object `auth/sign-in` takes: the method and the credentials it needs. */
+type HostSignInRequest = {
+    method: 'google';
+} | {
+    method: 'email';
+    email: string;
+    password: string;
+} | {
+    method: 'emailLink';
+    email: string;
+    continueUrl: string;
+} | {
+    method: 'emailLink';
+    email: string;
+    link: string;
+} | {
+    method: 'customToken';
+    token: string;
+};
+/** What a sign-in answers: the viewer, or `{ sent: true }` for an email link that was only sent. */
+type HostSignInAnswer = {
+    uid: string;
+    email?: string;
+    displayName?: string;
+} | {
+    sent: true;
+};
+/** The one object `auth/consent` takes: the authorize URL the viewer is sent to. */
+interface HostConsentRequest {
+    authorizeUrl: string;
+}
+/** What a consent answers: the `code` and `state` query params of the final redirect URL, read as they are. */
+interface HostConsentAnswer {
+    code: string;
+    state: string;
+}
+/** Why a host ask failed: the viewer closed it, the provider denied it, the request was malformed, or the host has no such action. */
+type HostAskFailureKind = 'cancelled' | 'denied' | 'invalid' | 'unavailable';
+/** A host action's own failure, carrying the kind the completion reports. */
+declare class HostAskError extends Error {
+    readonly kind: HostAskFailureKind;
+    constructor(kind: HostAskFailureKind, message: string);
+}
+/** What the client host does for the `audio/*`, `auth/sign-out`, `auth/sign-in` and `auth/consent` asks; a host that has none refuses them by name. */
+interface KernelHostActions {
+    audio?: (ask: HostAudioAsk) => void;
+    signOut?: () => void | Promise<void>;
+    signIn?: (request: HostSignInRequest) => Promise<HostSignInAnswer>;
+    consent?: (request: HostConsentRequest) => Promise<HostConsentAnswer>;
+}
+/** A host ask's answer: the payload of its success route, or the error and kind of its failure route. */
+type HostAskOutcome = {
+    ok: JsonObject;
+} | {
+    error: string;
+    kind: HostAskFailureKind;
+};
+/** The event a host's answer dispatches: to `trait` (on `entityId` when the frame is a row), carrying `payload`. */
+interface HostAskReturn {
+    trait: string;
+    entityId?: string;
+    event: string;
+    payload: JsonObject;
+}
 interface KernelHostPorts {
+    hostActions?: KernelHostActions;
     pageFacts?: (fields: readonly PageFactField[]) => BrowserPageFacts;
     persistence: PersistenceAdapter;
     callService: KernelCallService;
@@ -52,8 +128,8 @@ interface KernelHostPorts {
     }, payload: EventPayload, originClientId: string | undefined) => void;
     /** Read per call: the sink a follow-on call's outcome runs through, absent when the host cannot deliver it to the tab. */
     deferCallOutcome: () => ((call: DeferredCallOutcome) => void) | undefined;
-    /** The `http` effect's ports (kernel builder, secrets, egress); absent, an `http` ask fails as unavailable. */
-    http?: HttpPorts;
+    /** The secret store, CSPRNG and credential administration ports the kernel's secret, random and credential asks use. */
+    secretPorts?: SecretPorts;
     /** The on-device model and embedder; absent, a `browser/prompt` or `browser/embed` ask fails `unconfigured`. */
     onDevice?: OnDeviceModelPorts;
     /** The browser's tabs for the `browser/tab-*` effects; absent, a tab ask fails `unavailable`. */
@@ -62,6 +138,10 @@ interface KernelHostPorts {
     os?: OsHostPort;
     /** What the kernel decides about a deferred `os` call (which ops defer, the event an outcome fires); absent, every `os` ask is answered in place. */
     osCompletions?: OsCompletionPort;
+    /** The kernel's TLS state for sockets it owns (EXEC-HTTP-7); absent, a deferred outcome reaches its route as the host gave it. */
+    osTls?: OsTlsPort;
+    /** The kernel's typed parse of a `program/dispatch` event request; absent, that ask is refused. */
+    parseEventRequest?: EventRequestParser;
     substrateStream?: (op: string, args: readonly JsonValue[], scope: KernelAnswerScope) => SubstrateStreamSource | undefined;
     substrateMessage?: (site: CallSiteWire, key: string, value: JsonValue) => OsCompletionEvent | null;
     substrateCompletion?: (site: CallSiteWire, key: string, op: string, args: readonly JsonValue[], outcome: Settled<JsonValue, SubstrateFailureWire>) => OsCompletionEvent | null;
@@ -72,17 +152,48 @@ interface KernelHostPorts {
 interface KernelAnswerScope {
     /** The orbital the request is addressed to. */
     orbital: string;
-    /** The viewer the dispatch runs as; a substrate operator is called as them. */
-    user?: UserContext;
     /** The requesting tab. */
     originClientId?: string;
     locale?: string;
     entityId?: string;
-    /** Runs `work` with the host's event queue released (a service call must not hold the next event). */
-    outsideEventQueue?: <T>(work: () => Promise<T>) => Promise<T>;
     onStream?: (item: EventStreamItem) => void;
     assertReentry?: () => void;
 }
+/** The kernel's typed parse of a `program/dispatch` event request: the request, or the reason it is none. */
+type EventRequestParser = (payload: JsonObject, options: JsonObject) => Settled<EventRequest, string>;
+/** The request parser over the kernel module: `EventRequest::from_dispatch`, not copied. */
+declare function kernelEventRequestParser(kernel: Pick<KernelModule, 'parseEventRequest'>): EventRequestParser;
+/** `audio/*` and `auth/sign-out`: one ask each, performed by the host's actions; a host without them refuses by name. */
+declare function performHostAsk(actions: KernelHostActions | undefined, op: string, args: readonly JsonValue[]): Promise<Settled<null, string>>;
+/** The `auth/sign-in` request an ask carries, or why it is refused before the host is asked. */
+declare function parseSignInRequest(args: readonly JsonValue[]): {
+    request: HostSignInRequest;
+} | {
+    error: string;
+};
+/** The `auth/consent` request an ask carries, or why it is refused before the host is asked. */
+declare function parseConsentRequest(args: readonly JsonValue[]): {
+    request: HostConsentRequest;
+} | {
+    error: string;
+};
+/** The `code` and `state` query params of a consent's final redirect URL, read as they are; a redirect without both is a denial. */
+declare function consentFromRedirect(redirectUrl: string): HostConsentAnswer;
+/** The answer of one host ask whose completion the host returns: `auth/sign-in` through the host's sign-in, `auth/consent` through its consent, any other op as it is performed (an empty success). */
+declare function performHostAnswer(actions: KernelHostActions | undefined, op: string, args: readonly JsonValue[]): Promise<HostAskOutcome>;
+/** The event `outcome` fires on the ask's declared route, or undefined when the ask declared none for it (nothing fires). */
+declare function hostAskReturn(completion: HostAskCompletion, outcome: HostAskOutcome): HostAskReturn | undefined;
+/**
+ * A deferred raw `os` outcome that belongs to a TLS operation the kernel parked (EXEC-HTTP-7) is finished in the kernel:
+ * it decrypts or encrypts the raw outcome and, while it needs more raw bytes, asks the host's `os` port for them. Any
+ * other key's outcome is returned as it stands.
+ */
+declare function finishTls(ports: KernelHostPorts, os: OsHostPort, key: string, raw: Settled<JsonValue, OsError>): Promise<Settled<JsonValue, OsError>>;
+/**
+ * The same loop, handing the outcome to `finish` in the calling turn whenever the kernel needs no further raw ask
+ * (nothing parked, or done at once); only a parked operation's follow-up ask makes it wait (EXEC-QUEUE-10/13).
+ */
+declare function completeTls(ports: KernelHostPorts, os: OsHostPort, key: string, raw: Settled<JsonValue, OsError>, finish: (outcome: Settled<JsonValue, OsError>) => void): void;
 declare function writeRows(persistence: PersistenceAdapter, request: Extract<IoRequestWire, {
     kind: 'writeRows';
 }>): Promise<IoAnswerWire>;
@@ -91,5 +202,5 @@ declare function declareCapabilities(persistence: PersistenceAdapter, declare: (
 /** Answer one request of the kernel; a thrown adapter error becomes the request's declared failure. */
 declare function answerRequest(ports: KernelHostPorts, request: IoRequestWire, scope: KernelAnswerScope): Promise<IoAnswerWire>;
 
-export { answerRequest, declareCapabilities, writeRows };
-export type { DeferredCallOutcome, KernelAnswerScope, KernelCallService, KernelHostPorts, SubstrateStreamSource };
+export { HostAskError, answerRequest, completeTls, consentFromRedirect, declareCapabilities, finishTls, hostAskReturn, kernelEventRequestParser, parseConsentRequest, parseSignInRequest, performHostAnswer, performHostAsk, writeRows };
+export type { DeferredCallOutcome, EventRequestParser, HostAskFailureKind, HostAskOutcome, HostAskReturn, HostAudioAsk, HostConsentAnswer, HostConsentRequest, HostSignInAnswer, HostSignInRequest, KernelAnswerScope, KernelCallService, KernelHostActions, KernelHostPorts, SubstrateStreamSource };

package/dist/kernel/host.js

@@ -1,9 +1,6 @@
-export { answerRequest, declareCapabilities, writeRows } from '../chunk-NATGCIVM.js';
-import '../chunk-HNOAZWFH.js';
-import '../chunk-YO4LWS3I.js';
-import '../chunk-MZKIL5IN.js';
+export { HostAskError, answerRequest, completeTls, consentFromRedirect, declareCapabilities, finishTls, hostAskReturn, kernelEventRequestParser, parseConsentRequest, parseSignInRequest, performHostAnswer, performHostAsk, writeRows } from '../chunk-7WB6VWRK.js';
+import '../chunk-WGCWJOT2.js';
+import '../chunk-ZUSM4VW4.js';
 import '../chunk-FWA5K7Q2.js';
-import '../chunk-VMOBW7RK.js';
-import '../chunk-RBUMDYFS.js';
 import '../chunk-HLOUDLPI.js';
-import '../chunk-MLKGABMK.js';
+import '../chunk-MZKIL5IN.js';

package/dist/kernel/lane.d.ts

@@ -1,28 +1,7 @@
-interface LaneTurn {
-    readonly ticket: number;
-}
 declare class LaneHeldByParkedDispatch extends Error {
     readonly ticket: number;
     readonly event: string;
     constructor(ticket: number, event: string);
 }
-interface LaneGuard {
-    readonly turn: LaneTurn;
-    park(event: string): void;
-    resume(): void;
-    release(): void;
-}
-declare class DispatchLane {
-    private nextTicket;
-    private holder;
-    private depth;
-    private parkedEvent;
-    private readonly waiters;
-    assertCanReenter(turn: LaneTurn): void;
-    enter(turn?: LaneTurn): Promise<LaneGuard>;
-    private take;
-    private guard;
-}
 
-export { DispatchLane, LaneHeldByParkedDispatch };
-export type { LaneGuard, LaneTurn };
+export { LaneHeldByParkedDispatch };

package/dist/kernel/lane.js

@@ -1,2 +1 @@
-export { DispatchLane, LaneHeldByParkedDispatch } from '../chunk-53IPZXDP.js';
-import '../chunk-MLKGABMK.js';
+export { LaneHeldByParkedDispatch } from '../chunk-NU6LVKGS.js';

package/dist/kernel/os-fetch-port.d.ts

@@ -0,0 +1,7 @@
+import { OsHostPort } from './os-port.js';
+import '@almadar/core';
+import '@almadar/core/kernel-wire';
+
+declare function createFetchOsHost(performFetch: typeof fetch): OsHostPort;
+
+export { createFetchOsHost };

package/dist/kernel/os-fetch-port.js

@@ -0,0 +1,3 @@
+export { createFetchOsHost } from '../chunk-625EP7W2.js';
+import '../chunk-ZUSM4VW4.js';
+import '../chunk-HLOUDLPI.js';

package/dist/kernel/os-port.d.ts

@@ -39,8 +39,8 @@ type OsRequirement = {
 };
 /** The grant decisions the wasm kernel owns (`OsGrants::allows`, the one-grant glob matcher, `is_public_address`). */
 interface OsGrantPort {
-    /** `OsGrants::allows` over the grants every registered program declares. */
-    allows(need: OsRequirement): boolean;
+    /** `OsGrants::allows` over the grants of `orbital` (its own plus the app level); with no orbital, the app level alone. */
+    allows(need: OsRequirement, orbital?: string): boolean;
     /** Whether the absolute `glob` (`**`, `*`, `?`) matches `path`, as a one-grant `fs_allows` for read. */
     globMatches(glob: string, path: string): boolean;
     /** `is_public_address`: the rule an outbound host name must pass. */
@@ -57,19 +57,20 @@ interface OsAnchorProblem {
 }
 /** What a host answers an `os` ask with; `close` drops every handle it holds, as the native `OsHandles::close_all`. */
 interface OsHostPort {
-    answer(op: OsOp, args: JsonValue[]): Promise<Settled<JsonValue, OsError>>;
+    /** `orbital` is the orbital whose trait made the ask: its grants (plus the app's) answer it. */
+    answer(op: OsOp, args: JsonValue[], orbital?: string): Promise<Settled<JsonValue, OsError>>;
     /**
      * `Completions::run_later`: a keyed ask of a completion-deferring op. A failed check (or a key already pending) is the
      * in-place `error`; `ok` means the work runs in the background and its outcome reaches `deliver` once, unless
      * the key is cancelled first. A host with no `defer` answers every ask in place.
      */
-    defer?(op: OsOp, args: JsonValue[], key: string, deliver: (outcome: Settled<JsonValue, OsError>) => void): Settled<null, OsError>;
+    defer?(op: OsOp, args: JsonValue[], key: string, deliver: (outcome: Settled<JsonValue, OsError>) => void, orbital?: string): Settled<null, OsError>;
     /**
      * A keyed stream (`OsOp::is_stream`, EXEC-QUEUE-12): the host binds and answers once in place, then hands each message
      * to `message` until it ends; `message` answers `false` when no one takes it any more. A failure after the answer
      * reaches `fail` once. A host with no `stream` answers every stream ask in place, as unsupported.
      */
-    stream?(op: OsOp, args: JsonValue[], key: string, message: (value: JsonValue) => boolean, fail: (error: OsError) => void): Promise<Settled<JsonValue, OsError>>;
+    stream?(op: OsOp, args: JsonValue[], key: string, message: (value: JsonValue) => boolean, fail: (error: OsError) => void, orbital?: string): Promise<Settled<JsonValue, OsError>>;
     /** `OsHandles::cancel_completion`: drop the pending completion of `key`, or stop its stream; `false` when none is open. */
     cancel?(key: string): boolean;
     close(): void;
@@ -85,6 +86,26 @@ interface OsCompletionPort {
     streams(op: OsOp): boolean;
     event(site: CallSiteWire, key: string, outcome: Settled<JsonValue, OsError>): OsCompletionEvent | null;
 }
+/** The next step of a TLS operation the kernel parked on a deferred raw ask. */
+type OsTlsStep = {
+    ask: {
+        op: OsOp;
+        args: JsonValue[];
+    };
+} | {
+    done: Settled<JsonValue, OsError>;
+};
+/** The kernel's TLS sockets (EXEC-HTTP-7): the host's raw outcome of a deferred ask goes in, the next raw ask or the program's outcome comes out. */
+interface OsTlsPort {
+    /** `null` when `key` parks no TLS operation. */
+    complete(key: string, outcome: Settled<JsonValue, OsError>): OsTlsStep | null;
+}
+/** The server handle's TLS export. */
+interface OsTlsKernel {
+    tlsComplete(key: string, outcomeJson: string): string;
+}
+/** The TLS port over the kernel `Server` handle: every decision is `RuntimeKernel::tls_complete`. */
+declare function kernelOsTls(server: () => OsTlsKernel): OsTlsPort;
 /** The kernel exports the completion port is built from. */
 interface OsCompletionMatchers {
     osDeferringOps(): string;
@@ -95,7 +116,7 @@ interface OsCompletionMatchers {
 declare function kernelOsCompletions(kernel: OsCompletionMatchers): OsCompletionPort;
 /** The kernel pieces a grant port is built from: the `Server` handle holding the program's grants and the module-level matchers. */
 interface OsGrantKernel {
-    osAllows(requirementJson: string): boolean;
+    osAllows(requirementJson: string, orbital?: string): boolean;
     setOsAnchors(anchorsJson: string): string;
     osResolveArgs(op: string, argsJson: string): string;
 }
@@ -113,6 +134,7 @@ interface OsAnchors {
     readonly home?: string;
     readonly start?: string;
     readonly exeDir?: string;
+    readonly exe?: string;
     readonly env?: Readonly<Record<string, string>>;
 }
 /** What a written path names under the host's anchors (`OsAnchors::expand`). */
@@ -129,5 +151,5 @@ declare function expandAnchor(anchors: OsAnchors, text: string): AnchoredPath;
 /** The grant port a host checks absolute paths through: an fs need also matches the program's `~/` and `./` grants (`OsGrants::fs_allows_at`). */
 declare function anchoredGrants(grants: OsGrantPort, anchors: OsAnchors): OsGrantPort;
 
-export { anchoredGrants, expandAnchor, kernelOsCompletions, kernelOsGrants };
-export type { AnchoredPath, OsAnchorProblem, OsAnchors, OsCompletionEvent, OsCompletionMatchers, OsCompletionPort, OsDesktopKind, OsFsMode, OsGrantKernel, OsGrantMatchers, OsGrantPort, OsHostPort, OsNetKind, OsRequirement, OsStdioKind, OsSysKind };
+export { anchoredGrants, expandAnchor, kernelOsCompletions, kernelOsGrants, kernelOsTls };
+export type { AnchoredPath, OsAnchorProblem, OsAnchors, OsCompletionEvent, OsCompletionMatchers, OsCompletionPort, OsDesktopKind, OsFsMode, OsGrantKernel, OsGrantMatchers, OsGrantPort, OsHostPort, OsNetKind, OsRequirement, OsStdioKind, OsSysKind, OsTlsKernel, OsTlsPort, OsTlsStep };

package/dist/kernel/os-port.js

@@ -1,2 +1 @@
-export { anchoredGrants, expandAnchor, kernelOsCompletions, kernelOsGrants } from '../chunk-REPX5QPI.js';
-import '../chunk-MLKGABMK.js';
+export { anchoredGrants, expandAnchor, kernelOsCompletions, kernelOsGrants, kernelOsTls } from '../chunk-BOVU4TCQ.js';

package/dist/kernel/program-effects.d.ts

@@ -1,7 +1,9 @@
-import { ProgramInspection, CatalogEntry, TraitDescription, BehaviorDescription, OrbitalSchema, EvaluatedProgram, ProgramValidationIssue, DependencyGraph, EventPayload, CircuitStepResult } from '@almadar/core';
+import { ProgramInspection, CatalogEntry, TraitDescription, BehaviorDescription, OrbitalSchema, EvaluatedProgram, ProgramValidationIssue, DependencyGraph, EventPayload } from '@almadar/core';
+import { ProveReport, OsGrantsReport, PlayedStep } from '@almadar/core/kernel-wire';
+export { PlayedStep } from '@almadar/core/kernel-wire';
 
 /** The effects the language trio routes to this host. */
-declare const PROGRAM_EFFECTS: readonly ["behavior/catalog", "behavior/describe", "behavior/source", "behavior/resolve", "behavior/dependencies", "program/read", "program/print", "program/eval", "program/validate", "program/compose", "program/step"];
+declare const PROGRAM_EFFECTS: readonly ["behavior/catalog", "behavior/describe", "behavior/source", "behavior/resolve", "behavior/dependencies", "program/read", "program/print", "program/eval", "program/validate", "program/prove", "program/os-grants", "program/compose", "program/step"];
 type ProgramEffectName = (typeof PROGRAM_EFFECTS)[number];
 /** Narrow an effect head to one this host runs. */
 declare function isProgramEffect(name: string): name is ProgramEffectName;
@@ -26,35 +28,16 @@ interface StepRequest {
     now?: number;
     /** A live call's cutoff: an open call still running after this many ms is cancelled. */
     settleMs?: number;
-    /** The user the request dispatches as (`@user`); null or absent is nobody. */
-    viewer?: EventPayload | null;
-}
-/** One trait the step's dispatch cascade moved, in dispatch order. */
-interface CascadeOutcome {
-    orbital: string;
-    trait: string;
-    /** The event this trait handled (a listener's own triggered event). */
-    event: string;
-    from: string;
-    to: string;
-    /** The arm that fired; null when none did. */
-    arm: number | null;
-    fired: boolean;
-    /** The effects of the arm this trait fired, as the top-level `effects` report them. */
-    effects: CircuitStepResult['effects'];
-    emitted: CircuitStepResult['emitted'];
-}
-/** A played request: the request as asked, and the circuit it ran, with every trait its cascade moved. */
-type PlayedStep = StepRequest & {
-    result: CircuitStepResult & {
-        outcomes: CascadeOutcome[];
-        entityAfter: EventPayload | null;
+    /** Test-only: the verified identity the replay kernel binds for this step (`@user`); absent is the anonymous viewer. */
+    identity?: {
+        subject: string;
+        claims: EventPayload;
     };
-};
+}
 /** The outcome of one program effect: the value for `{ result }`, or the failure (`errors` for eval's validator issues). */
 type ProgramEffectOutcome = {
     readonly ok: true;
-    readonly result: ProgramInspection | CatalogEntry[] | TraitDescription | BehaviorDescription | OrbitalSchema | string | EvaluatedProgram | ProgramValidationReport | DependencyGraph | PlayedStep[];
+    readonly result: ProgramInspection | CatalogEntry[] | TraitDescription | BehaviorDescription | OrbitalSchema | string | EvaluatedProgram | ProgramValidationReport | ProveReport | OsGrantsReport | DependencyGraph | PlayedStep[];
 } | {
     readonly ok: false;
     readonly error: string;
@@ -62,4 +45,4 @@ type ProgramEffectOutcome = {
 };
 
 export { PROGRAM_EFFECTS, isProgramEffect };
-export type { CascadeOutcome, PlayedStep, ProgramEffectName, ProgramEffectOutcome, ProgramValidationReport, StepRequest };
+export type { ProgramEffectName, ProgramEffectOutcome, ProgramValidationReport, StepRequest };

package/dist/kernel/program-effects.js

@@ -1,2 +1 @@
-export { PROGRAM_EFFECTS, isProgramEffect } from '../chunk-HNOAZWFH.js';
-import '../chunk-MLKGABMK.js';
+export { PROGRAM_EFFECTS, isProgramEffect } from '../chunk-WGCWJOT2.js';

package/dist/kernel/secret-ports.d.ts

@@ -0,0 +1,139 @@
+import { RuntimeValue, CredentialPayload } from '@almadar/core';
+import { TokenEndpointPost, CredentialVault } from '../credentials/vault.js';
+import { CredentialGrantWire, CredentialStanding, ConnectFailure } from '@almadar/core/kernel-wire';
+
+/**
+ * The host ports of the kernel's secret, random and credential asks: the secret store, the CSPRNG and the credential
+ * administration port. The `http` effect is retired (HTTP/1.1 is `.lolo` over `os/*`), so nothing here moves HTTP bytes.
+ */
+
+/**
+ * The host's secret store: a credential NAME in, its value out; `set` keeps a minted value for `ttlMs`.
+ * `principal` is the signed-in user's id for a user-scoped credential (the kernel sets it from the dispatch's `@user`,
+ * never the program); absent, the credential is app-wide.
+ */
+interface SecretStore {
+    get(name: string, principal?: string): Promise<string | undefined>;
+    /** `ttlMs` of 0 forgets the value. */
+    set(name: string, value: string, ttlMs: number, principal?: string): Promise<void>;
+    /** Replace the stored credential with `value`, durably (a rotated refresh token). A host without one cannot rotate. */
+    rotate?(name: string, value: string, principal?: string): Promise<void>;
+    /** Drop the credential, the minted value and the stored one. */
+    forget(name: string, principal?: string): Promise<void>;
+    /** Keep `value` as the credential until it is forgotten, creating it when absent: unlike `rotate` it needs no existing entry. `label` is a non-secret account name stored beside it, never the value. */
+    persist?(name: string, value: string, principal?: string, label?: string): Promise<void>;
+    /** The non-secret account label stored beside the credential; absent when its row carries none. */
+    label?(name: string, principal?: string): Promise<string | undefined>;
+    /** Whether `persist` keeps a value on this host. */
+    durable?(): Promise<boolean>;
+}
+/** The credential-store key of one user's credential. */
+declare function userCredentialKey(principal: string, name: string): string;
+/** CSPRNG output: `bytes` random bytes. */
+type RandomSource = (bytes: number) => Uint8Array;
+/**
+ * The host's raw credential store and mode flag, answered to the kernel's `credentialStore*` and `credentialMode*`
+ * asks. It decides nothing: the role gate, the declared-name check, the masking and the mode check are the kernel's.
+ */
+interface CredentialAdminPort {
+    /** Whether the store can encrypt and the service and name of every stored row; `null` when the host holds no store. */
+    list(): Promise<{
+        enabled: boolean;
+        entries: Array<{
+            service: string;
+            name: string;
+        }>;
+    } | null>;
+    /** The stored value of credential `name`, from the store only. */
+    read(name: string): Promise<string | null>;
+    write(service: string, name: string, value: string): Promise<void>;
+    /** Whether a stored row existed. */
+    remove(name: string): Promise<boolean>;
+    rotate(): Promise<{
+        rotated: number;
+        alreadyCurrent: number;
+        unreadable: number;
+    }>;
+    /** The mode flag; `null` when the host keeps none. */
+    mode(): Promise<string | null>;
+    /** Switch the flag; the host may refuse. The mode in force afterwards. */
+    setMode(mode: string): Promise<string>;
+}
+/** The tails of the named variables this host's own environment holds: `last4` only from eight characters up, never a value. */
+type EnvTailsPort = (names: readonly string[]) => Array<{
+    name: string;
+    last4?: string;
+}>;
+/** The environment tails of `env`: a name it holds non-empty, with the last four characters of a value of eight or more. */
+declare function envTailsOf(env: Readonly<Record<string, string | undefined>>): EnvTailsPort;
+/** The host's answer to a `credentialConnect` ask: the kernel's store builds the exchange and settles it, the host only sends it. */
+type CredentialConnectPort = (grant: CredentialGrantWire) => Promise<{
+    ok: CredentialStanding;
+} | {
+    error: ConnectFailure;
+}>;
+interface SecretPorts {
+    /** The host CSPRNG `random-bytes` and the driver's `Random` ask draw from. */
+    random: RandomSource;
+    secrets: SecretStore;
+    /** The credential store and mode flag the credential administration effects ask; absent, those asks fail unavailable. */
+    credentials?: CredentialAdminPort;
+    /** The host's own environment, for `credential-list`; absent, the host answers `unsupported` (a browser reads none). */
+    env?: EnvTailsPort;
+    /** Carries a `credentialConnect`; absent, the ask answers `unavailable`. */
+    connect?: CredentialConnectPort;
+}
+interface SecretPortsOptions {
+    random?: RandomSource;
+    secrets?: SecretStore;
+    /** Defaults to the installed credential store and mode flag. */
+    credentials?: CredentialAdminPort;
+    /** Defaults to the process environment. */
+    env?: EnvTailsPort;
+    /** The host's POST to a token endpoint; with it the credential store connects and refreshes OAuth credentials, without it neither is attempted. */
+    tokenPost?: TokenEndpointPost;
+}
+/** Where the secrets' durable credentials live: the store a host installed, and how a name resolves through it. */
+interface SecretStoreHost {
+    store(): Promise<CredentialVault | null>;
+    resolve(name: string, principal: string | undefined): Promise<string | undefined>;
+}
+/**
+ * The secrets of a host: minted values with an expiry (a memory tier that never reaches the rows), then the credential vault
+ * the host holds (by default the one the host installed). Everything durable is the kernel's: `rotate`, `persist`, `label`,
+ * and `forget`.
+ */
+declare function createSecretStore(now?: () => number, host?: SecretStoreHost, tokenPost?: TokenEndpointPost): SecretStore;
+/** `credentialConnect` over the installed credential store and the host's token POST. */
+declare function createCredentialConnectPort(post: TokenEndpointPost): CredentialConnectPort;
+/** The credential store and mode flag the host installed, as the kernel's raw asks. */
+declare function createCredentialAdminPort(): CredentialAdminPort;
+/** Bytes from the platform CSPRNG. */
+declare const systemRandom: RandomSource;
+/** The most bytes one `random-bytes` may ask for (the kernel's `RANDOM_BYTES_MAX`). */
+declare const RANDOM_BYTES_MAX = 1024;
+/** Standard padded base64 (the wire form of a `Random` answer). */
+declare function base64Standard(bytes: Uint8Array): string;
+/** URL-safe base64 without padding (the `random-bytes` value; the kernel's `codec::base64url_encode`). */
+declare function base64Url(bytes: Uint8Array): string;
+/**
+ * `random-bytes`: the success payload for `bytes` drawn from the host CSPRNG; a bad count or key is the effect's
+ * failure. A keyed call echoes its `key` beside the `value`.
+ */
+declare function randomBytesPayload(ports: Pick<SecretPorts, 'random'>, bytes: RuntimeValue | undefined, key?: RuntimeValue): {
+    value: string;
+    key?: string;
+};
+/** `credential-status`: a bare name selects the viewer; an explicit slot selects its declared scope. */
+declare function credentialStatusPayload(ports: Pick<SecretPorts, 'secrets'>, credential: RuntimeValue | undefined, principal: string | undefined): Promise<CredentialPayload>;
+/** `credential-forget`: drops the signed-in viewer's credential; `{ connected: false }`. */
+declare function credentialForgetPayload(ports: Pick<SecretPorts, 'secrets'>, credential: RuntimeValue | undefined, principal: string | undefined): Promise<{
+    connected: false;
+    label: string;
+}>;
+declare function createSecretPorts(options?: SecretPortsOptions): SecretPorts;
+/** Ports of a browser: it holds no credential, so a secret ask fails and the CSPRNG is the page's. */
+declare function createBrowserSecretPorts(): SecretPorts;
+
+export { RANDOM_BYTES_MAX, base64Standard, base64Url, createBrowserSecretPorts, createCredentialAdminPort, createCredentialConnectPort, createSecretPorts, createSecretStore, credentialForgetPayload, credentialStatusPayload, envTailsOf, randomBytesPayload, systemRandom, userCredentialKey };
+export type { CredentialAdminPort, CredentialConnectPort, EnvTailsPort, RandomSource, SecretPorts, SecretPortsOptions, SecretStore, SecretStoreHost };

package/dist/kernel/secret-ports.js

@@ -0,0 +1,2 @@
+export { RANDOM_BYTES_MAX, base64Standard, base64Url, createBrowserSecretPorts, createCredentialAdminPort, createCredentialConnectPort, createSecretPorts, createSecretStore, credentialForgetPayload, credentialStatusPayload, envTailsOf, randomBytesPayload, systemRandom, userCredentialKey } from '../chunk-ZUSM4VW4.js';
+import '../chunk-HLOUDLPI.js';