@byok-sdk/core 0.2.0 → 0.4.0

package/dist/mailbox.d.ts

@@ -35,16 +35,28 @@ export interface MailboxMessage {
     readonly state: MailboxMessageState;
     readonly appendedAt: string;
 }
-export interface MailboxAppendInput {
-    readonly deviceId: string;
+/** Opaque bytes produced after the mailbox has atomically reserved their delivery sequence. */
+export interface MailboxBody {
     readonly body: string;
     readonly bodyHash: ContentHash;
     readonly byteSize: bigint;
+}
+export interface MailboxAppendInput {
+    readonly deviceId: string;
     /**
      * Producer-supplied idempotency key. A second append with the same
      * `messageId` returns the existing row instead of enqueuing a duplicate.
      */
     readonly messageId: string;
+    /**
+     * Builds the opaque body around the sequence reserved by this append.
+     *
+     * The store invokes this only for a new row and commits the returned bytes
+     * at exactly that `seq`. Allocation, materialization, and insertion are one
+     * per-device serialized operation; otherwise concurrent offers could commit
+     * out of order and let an ack skip a late lower sequence.
+     */
+    readonly materialize: (seq: number) => MailboxBody | Promise<MailboxBody>;
 }
 export interface MailboxReadQuery {
     readonly deviceId: string;

package/dist/pairing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Nonce-signing domain separation for device token renewal (docs/protocol.md §6.2).
+ *
+ * S1 (GAP-004) put a domain tag in front of every challenge nonce a device
+ * signs: the device key is a long-lived identity key that other planes (S6
+ * device proof) also sign structured messages with, so without a tag a
+ * signature produced for one purpose would be a valid signature for another.
+ *
+ * The tag started life as three separate literals — one in the daemon, one on
+ * the hosted surface, one on the reference server — each with a comment saying
+ * it was byte-identical to the others. That is a drift hazard written down, not
+ * a design: three copies agree only until someone edits one. This module is the
+ * single authority, and it lives in core for the same reason
+ * {@link DEVICE_PROOF_DOMAIN_PREFIX} does — core is the one package all three
+ * ends already depend on, it is Node-free and Workers-safe, and it holds no
+ * crypto of its own. What travels is *bytes to sign*; who signs them, and with
+ * which primitive, stays with each end.
+ *
+ * There is deliberately no dual mode and no grace window: a raw, unprefixed
+ * nonce signature is simply invalid, and a device on an older encoding re-pairs.
+ */
+/**
+ * The domain-separation prefix a device signs along with a challenge nonce.
+ *
+ * Byte-frozen: `62 79 6f 6b 2d 6e 6f 6e 63 65 2d 76 31 0a` (14 bytes, UTF-8).
+ * Changing it invalidates every deployed device's token-renewal path, so it is
+ * a wire constant, not a tunable.
+ */
+export declare const NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
+/**
+ * The exact bytes a device signs for a challenge nonce, and the exact bytes a
+ * verifier reconstructs: {@link NONCE_SIGNING_DOMAIN} followed by `nonce`,
+ * UTF-8 encoded.
+ *
+ * `TextEncoder` is a platform global on Node and Workers alike, which is what
+ * lets the one authority sit in a package that imports no `node:` builtin.
+ */
+export declare function nonceSigningBytes(nonce: string): Uint8Array;

package/dist/ports-contract.d.ts

@@ -20,7 +20,24 @@
  * Adding a port method means editing this table, which is the point: a port
  * grows by contract, not by whichever composition needed something.
  */
-import type { CoreStoreName } from './stores';
+import { type CoreStoreName } from './stores';
+/**
+ * Ports that are core ports but NOT members of the composition contract.
+ *
+ * Now empty, and that is the whole point of Phase 2. Phase 1 of
+ * `skill-pack-delivery-channel` held `skillPacks` here as a self-declared
+ * temporary bridge: adding it to `CoreStores` before its Postgres
+ * implementation existed would have obliged every composition to implement it
+ * in the same slice, and the alternatives — an optional port member (a
+ * compatibility fallback, forbidden) or a port outside the contract table
+ * entirely (exempt from the tenant-first scan, the one rule most worth having)
+ * — were both worse. Phase 2 delivered that implementation and moved
+ * `skillPacks` into `CORE_STORE_NAMES`, so this list goes back to empty exactly
+ * as the Phase 1 note promised. The empty set stays named rather than deleted:
+ * it is the testable statement "every core port is a composition member", which
+ * `CORE_STORE_NAMES` alone cannot make.
+ */
+export declare const CORE_NON_COMPOSITION_PORT_NAMES: readonly [];
 export declare const CORE_PORT_METHODS: Readonly<Record<CoreStoreName, readonly string[]>>;
 /** The interface each port name is declared as, for the source-side scan. */
 export declare const CORE_PORT_INTERFACES: Readonly<Record<CoreStoreName, string>>;

package/dist/presence.d.ts

@@ -27,6 +27,12 @@ export interface PresenceHint {
     readonly level: PresenceLevel;
     /** Free-form host label, bounded by the composition. Never parsed by core. */
     readonly detail?: string;
+    /**
+     * Logical MCP toolset IDs this daemon reported as configured. Discovery
+     * only: local task acceptance remains the fail-closed authority. Omission
+     * means legacy/unknown; an empty array means known-none.
+     */
+    readonly configuredToolsets?: readonly string[];
     readonly observedAt: string;
     readonly expiresAt: string;
 }
@@ -34,6 +40,8 @@ export interface PresenceHintInput {
     readonly deviceId: string;
     readonly level: PresenceLevel;
     readonly detail?: string;
+    /** Validated logical IDs only; executable connector definitions never belong here. */
+    readonly configuredToolsets?: readonly string[];
     /** Hint lifetime. §12.7.5 suggests 60-120s for presence. */
     readonly ttlMs: number;
     /** Minimum time between accepted publications for this device. `0` explicitly disables throttling. */

package/dist/skill-pack.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Skill packs: declarative content a SaaS deployment distributes to a paired
+ * device (plan `skill-pack-delivery-channel`, Phase 1).
+ *
+ * A pack is an `agentskills.io`-shaped `SKILL.md` plus its static companion
+ * files. That is the WHOLE of it, and the narrowness is the design:
+ *
+ * 1. **No executable surface, by schema.** {@link SkillPackManifestSchema} is a
+ *    `strictObject`, so an unknown key is a rejection rather than a field
+ *    someone's tooling might later start honoring, and
+ *    {@link SKILL_PACK_FORBIDDEN_FIELDS} names the specific ones — `exec`,
+ *    `env`, `credential`, `hooks`, `allowed-tools` — that get their own
+ *    rejection message. The credential-isolation rule this SDK is built around
+ *    (§9.1) cannot be enforced downstream if the manifest can carry a command
+ *    to run or an environment to run it in, so it is enforced here, once.
+ * 2. **Every declared limit has an evaluation point in this file.** A size cap
+ *    that nothing measures, a path rule that nothing checks, and a content hash
+ *    that nothing verifies are the same failure: a security claim with no
+ *    enforcement behind it. {@link checkSkillPackManifest} evaluates the
+ *    manifest-level limits and {@link checkSkillPackFileContent} evaluates the
+ *    byte-level ones, both returning a named rejection instead of a boolean, so
+ *    a caller can say which limit fired.
+ * 3. **Hashing lives outside core.** Core has no `node:` import and no crypto
+ *    (the same rule `blob.ts` and `attestation.ts` follow), so this module owns
+ *    the canonical bytes a hash is taken over ({@link skillPackContentHashInput})
+ *    and the comparison, never the digest itself. The installer supplies what it
+ *    observed; core decides whether that is acceptable.
+ *
+ * Distribution is hosted HTTP (`@byok-sdk/cloud`'s `GET /byok/skill-packs`),
+ * declared through ADR-010 as `skills.pack`. Nothing here touches the frozen v1
+ * wire envelope, and there is deliberately no new message type: a pack is
+ * content a device PULLS after reading a declaration, not a message a server
+ * pushes into a task stream.
+ */
+import { z } from 'zod';
+import { type ContentHash } from './blob';
+import type { TenantId } from './tenant';
+export declare const SKILL_PACK_MANIFEST_SCHEMA_ID = "byok-skill-pack-v1";
+/**
+ * Pack names: lowercase, starting alphanumeric — the same shape
+ * `OBJECT_KEY_PREFIX_PATTERN` accepts per segment, for the same reason. A pack
+ * name becomes a directory name on a real device filesystem, so the accepted
+ * set is the one that reaches disk spelled exactly as declared: no case folding
+ * to collide over, no separator, no leading dot, nothing needing escaping.
+ */
+export declare const SKILL_PACK_NAME_PATTERN: RegExp;
+export declare const SKILL_PACK_NAME_MAX_LENGTH = 64;
+export declare const SKILL_PACK_DESCRIPTION_MAX_LENGTH = 1024;
+/** `MAJOR.MINOR.PATCH`. A pack version orders two publications of one name; it is not a range language. */
+export declare const SKILL_PACK_VERSION_PATTERN: RegExp;
+/**
+ * Relative POSIX paths only: slash-joined segments of alphanumerics, `.`, `_`
+ * and `-`, each STARTING with an alphanumeric.
+ *
+ * That single "starts with an alphanumeric" rule is what closes the traversal
+ * class rather than a blocklist of spellings: `..` cannot match (a segment may
+ * not begin with `.`), an absolute path cannot match (no leading slash), an
+ * empty segment cannot match (`a//b`), a Windows drive or UNC path cannot match
+ * (no `:`, no `\`), a home-relative path cannot match (no `~`), and a dotfile
+ * cannot match either. A blocklist would have to anticipate every encoding of
+ * the same idea; this allowlist has nothing to anticipate.
+ */
+export declare const SKILL_PACK_FILE_PATH_PATTERN: RegExp;
+export declare const SKILL_PACK_FILE_PATH_MAX_LENGTH = 200;
+/** The entry file every pack must carry, spelled as `agentskills.io` spells it. */
+export declare const SKILL_PACK_ENTRY_PATH = "SKILL.md";
+/** Per-file ceiling, measured in BYTES over the observed content — never in characters. */
+export declare const SKILL_PACK_FILE_MAX_BYTES = 262144;
+/** Whole-pack ceiling, over the sum of the observed file sizes. */
+export declare const SKILL_PACK_MAX_BYTES = 1048576;
+export declare const SKILL_PACK_MAX_FILES = 64;
+/**
+ * Manifest keys that must never exist, listed so the prohibition is testable
+ * rather than implied.
+ *
+ * `strictObject` already rejects every unknown key, so this list adds no new
+ * authority — it adds a NAMED rejection for the subset that matters: an
+ * operator who sees `unrecognized key: "env"` learns nothing about why, and a
+ * reviewer reading the schema cannot tell whether the omission was a decision
+ * or an oversight. Pinned from both directions by
+ * `__tests__/skill-pack.test.ts`.
+ */
+export declare const SKILL_PACK_FORBIDDEN_FIELDS: readonly ['exec', 'command', 'entrypoint', 'run', 'script', 'shell', 'env', 'environment', 'credential', 'credentials', 'secret', 'secrets', 'token', 'apiKey', 'api_key', 'allowedTools', 'allowed-tools', 'hooks', 'preinstall', 'postinstall'];
+/** One file in a pack: where it goes, what it must hash to, and how big it is. */
+export declare const SkillPackFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    contentHash: z.ZodPipe<z.ZodString, z.ZodTransform<ContentHash, string>>;
+    byteSize: z.ZodNumber;
+}, z.core.$strict>;
+export type SkillPackFile = z.infer<typeof SkillPackFileSchema>;
+/**
+ * The published description of one pack.
+ *
+ * `contentHash` addresses the manifest AS A WHOLE — see
+ * {@link skillPackContentHashInput} — which is what makes an install
+ * content-addressed: two publications that differ in any field a device can
+ * observe land in two directories, and re-installing an unchanged pack is a
+ * no-op rather than a partial overwrite.
+ */
+export declare const SkillPackManifestSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"byok-skill-pack-v1">;
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        contentHash: z.ZodPipe<z.ZodString, z.ZodTransform<ContentHash, string>>;
+        byteSize: z.ZodNumber;
+    }, z.core.$strict>>;
+    contentHash: z.ZodPipe<z.ZodString, z.ZodTransform<ContentHash, string>>;
+}, z.core.$strict>;
+export type SkillPackManifest = z.infer<typeof SkillPackManifestSchema>;
+/**
+ * Parses a manifest fail-closed.
+ *
+ * @throws {ByokCoreError} code `skill_pack_manifest_invalid`.
+ */
+export declare function parseSkillPackManifest(input: unknown): SkillPackManifest;
+/**
+ * The exact bytes `manifest.contentHash` is the sha256 of.
+ *
+ * Written out here, in core, because both ends have to agree on it and neither
+ * end may derive its own version: the publisher hashes this string to mint the
+ * address, the installer hashes it again to verify what it fetched, and a
+ * disagreement between the two would make every install either falsely
+ * accepted or unconditionally rejected. Newline-delimited and terminated so no
+ * field's content can be shifted into the next field's position, and the file
+ * rows are sorted by path so two publishers that enumerate a directory in
+ * different orders still mint the same address.
+ */
+export declare function skillPackContentHashInput(manifest: {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly files: readonly SkillPackFile[];
+}): string;
+/** Every way a pack can be refused. One name per declared limit — see {@link SkillPackCheck}. */
+export declare const SKILL_PACK_REJECTIONS: readonly ['path-unsafe', 'duplicate-path', 'entry-missing', 'file-count-over-cap', 'file-over-cap', 'pack-over-cap', 'size-mismatch', 'hash-mismatch', 'name-mismatch'];
+export type SkillPackRejection = (typeof SKILL_PACK_REJECTIONS)[number];
+/**
+ * Outcome of a check. `bytes` is the measured total on the accept path so a
+ * caller can record what it admitted; a rejection always names WHICH limit
+ * fired, because "the pack was rejected" is not an operable message.
+ */
+export type SkillPackCheck = {
+    readonly ok: true;
+    readonly bytes: number;
+} | {
+    readonly ok: false;
+    readonly reason: SkillPackRejection;
+    readonly detail: string;
+};
+/** Non-throwing path-safety predicate — the one authority on what a pack may name. */
+export declare function isSkillPackPathSafe(path: string): boolean;
+/**
+ * The manifest-level limits, evaluated.
+ *
+ * Runs over a manifest that has already parsed, so the per-field caps zod owns
+ * are not re-litigated here. What is left is everything zod cannot see: the
+ * relationships BETWEEN files (a duplicate path, a missing entry file, a total
+ * that clears every per-file cap and still blows the pack cap).
+ */
+export declare function checkSkillPackManifest(manifest: SkillPackManifest): SkillPackCheck;
+/** What an installer actually measured for one file, as opposed to what the manifest declared. */
+export interface ObservedSkillPackFile {
+    readonly byteSize: number;
+    readonly contentHash: ContentHash;
+}
+/**
+ * The byte-level limits, evaluated against what was actually fetched.
+ *
+ * The asymmetry with {@link checkSkillPackManifest} is the point: the declared
+ * size is a claim by the publisher and the observed size is a fact about the
+ * bytes on the device, so the cap is enforced on the OBSERVED value. A check
+ * that only ever measured the declaration would pass a 4 KiB manifest row
+ * attached to a 40 MiB response.
+ */
+export declare function checkSkillPackFileContent(declared: SkillPackFile, observed: ObservedSkillPackFile): SkillPackCheck;
+/**
+ * `SKILL.md` frontmatter, in the `agentskills.io` shape: exactly `name` and
+ * `description`, both required.
+ *
+ * The allowlist is the whole contract. `allowed-tools`, `hooks` and friends are
+ * real fields in other skill dialects and every one of them widens what a pack
+ * can ask a runtime to do; a parser that merely IGNORED them would still let a
+ * pack ship them to a host that does not.
+ */
+export interface SkillFrontmatter {
+    readonly name: string;
+    readonly description: string;
+}
+/** The only frontmatter keys a pack may declare. */
+export declare const SKILL_FRONTMATTER_FIELDS: readonly ['name', 'description'];
+/**
+ * Parses and validates a `SKILL.md`'s frontmatter block.
+ *
+ * Deliberately not a YAML engine: this is a closed two-key grammar, and the
+ * whole reason to hand-write it is that a general parser would happily accept
+ * anchors, aliases, nested maps, multi-document streams and block scalars —
+ * every one of which is a way to express something this format has decided not
+ * to have. Anything outside the grammar is a rejection, never a skipped line.
+ *
+ * @throws {ByokCoreError} code `skill_pack_frontmatter_invalid`.
+ */
+export declare function parseSkillFrontmatter(text: string): SkillFrontmatter;
+/**
+ * The entry file's own declaration must agree with the manifest's.
+ *
+ * Two authorities naming the same pack is not a redundancy to tolerate — a
+ * device that installed under one name and handed the runtime a skill calling
+ * itself another would be projecting content nobody asked for.
+ */
+export declare function checkSkillPackEntry(manifest: SkillPackManifest, entryText: string): SkillPackCheck;
+/** One file's bytes, as the distribution surface hands them over. */
+export interface SkillPackFileContent {
+    readonly path: string;
+    readonly contentHash: ContentHash;
+    readonly byteSize: number;
+    /** UTF-8 text. A pack carries Markdown, YAML and static text assets — never binaries, never archives. */
+    readonly content: string;
+}
+/** What a publisher hands the store: the validated manifest plus the bytes it addresses. */
+export interface SkillPackPublishInput {
+    readonly manifest: SkillPackManifest;
+    readonly files: readonly {
+        readonly path: string;
+        readonly content: string;
+    }[];
+}
+export interface SkillPackListQuery {
+    readonly limit?: number;
+}
+/**
+ * Skill pack port. Tenant-first, async, content plus manifest.
+ *
+ * Registered in `ports-contract.ts` as a core PORT, and deliberately not (yet)
+ * a member of `CoreStores`: a composition contract that named it would oblige
+ * every existing composition to implement it in the same slice, and the
+ * Postgres implementation is Phase 2 of this plan. See `ports-contract.ts` for
+ * the full note on that split.
+ *
+ * Raises: `skill_pack_manifest_invalid` (a publish whose bytes disagree with
+ * the manifest it was handed).
+ */
+export interface SkillPackStore {
+    /** Idempotent per (tenant, name, contentHash). Publishing a changed pack under the same name replaces it. */
+    publish(tenant: TenantId, input: SkillPackPublishInput): Promise<SkillPackManifest>;
+    get(tenant: TenantId, name: string): Promise<SkillPackManifest | undefined>;
+    list(tenant: TenantId, query: SkillPackListQuery): Promise<readonly SkillPackManifest[]>;
+    readFile(tenant: TenantId, name: string, path: string): Promise<SkillPackFileContent | undefined>;
+}

package/dist/stores.d.ts

@@ -22,6 +22,7 @@ import type { BoardStore } from './board';
 import type { MailboxStore } from './mailbox';
 import type { ObjectStore } from './blob';
 import type { QuotaStore } from './quota';
+import type { SkillPackStore } from './skill-pack';
 import type { TruthStore } from './truth';
 /**
  * Injected time.
@@ -48,7 +49,15 @@ export interface CoreStores {
     readonly activity: ActivityStore;
     readonly objects: ObjectStore;
     readonly quota: QuotaStore;
+    /**
+     * Skill-pack storage is a MANDATORY member: every composition creates the
+     * tables and supplies the port (Phase 2 of `skill-pack-delivery-channel`).
+     * Storage presence is not capability advertisement — the wire route/capability
+     * stays optional in `@byok-sdk/cloud` (`includeSkillPacks`), and a deployment
+     * that never declares `skills.pack` simply keeps the tables empty.
+     */
+    readonly skillPacks: SkillPackStore;
 }
 /** Names of the ports in {@link CoreStores}, in contract order. */
-export declare const CORE_STORE_NAMES: readonly ['mailbox', 'board', 'truth', 'presence', 'activity', 'objects', 'quota'];
+export declare const CORE_STORE_NAMES: readonly ['mailbox', 'board', 'truth', 'presence', 'activity', 'objects', 'quota', 'skillPacks'];
 export type CoreStoreName = (typeof CORE_STORE_NAMES)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "BYOK SDK platform contracts: branded tenant identity, tenant-first store ports, device proof canonicalization, and the composition conformance reference",
   "type": "module",
   "license": "MIT",