Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

The private software-factory/provider-subscriptions entry supplies ProviderSubscriptionHost, parseSubscriptionPolicy, subscriptionPolicyDigest, wireError, limits and neutral types. It hosts only the reviewed factory.branch-health.polled.v1 definition and signed verification challenges. No application event, cursor replay, model call, publication or domain command is delivered.

Install the private tarball in your own Node 26.8.1+ application. Import and construction are passive. All storage, authentication, current local authority, real contact admission, cleanup scheduling, clock and CSPRNG nonce generation belong to the commissioned caller. The module requires no Factory, Journal, HTTP client or runtime npm dependency. Public declarations require only ES2024.

Caller-owned boundary

Supply the exact HostOptions types in the installed declarations. PrivateStore.transact must acquire one real store-wide write lock and the current local ACL-generation lock before reading state/time/authority, run the synchronous decision and check store/policy/principal/role, epoch/predecessor and deadline again at the durable commit fence. Revocation must use that same lock. A compare-and-swap on separate subscription rows cannot protect the final global slot. Commit/acknowledgement uncertainty is unknown, never rollback. Missing/replaced/copy-derived commissioned state refuses; bootstrap is a separate explicit caller action with an external store-incarnation witness.

The private state is exactly PrivateRoot, schema sf-mcp-subscriptions-private/1. Caller bootstrap records the policy digest, one real createdAt/lastSweepAt, nextEpoch 1 and empty bounded arrays. Allocated epochs are 1–1,000,000; nextEpoch 1,000,001 is an exhausted sentinel, never an allocated epoch. Cleanup/read/reconciliation require no new epoch. Never reset or reuse the high-water value.

The connector must reopen the actual pending subscription, attempt and challenge slot under the same current local revocation lock before contact. Compare current principal/Product/policy/permissionGeneration, epoch/predecessor, canonical URL/key digests, nonce/webhook/request identity, signed bytes and fixed deadline. Request copies are bindings, not a fresh authority lookup. It owns public-address DNS/connect/TLS/redirect qualification; this package contains no production connector. It may not start contact after deadline/cancellation/revocation. Already-offered effects may remain unknown. An abort or caller timeout is not evidence of no further contact.

The accepted test-only loopback receiver verifies the exact Standard Webhooks HMAC and rejects a wrong key. That proof does not qualify a public connector or establish that arbitrary receivers validate signatures. An echoed challenge alone does not prove key possession.

Wire and results

list(context, params) accepts omitted params, {} or {cursor:null}. Authenticated discovery denial returns no definitions; unauthenticated and unknown authority/store are fixed failures. subscribe takes name, exact arguments, webhook URL/secret, optional cursor null, ttlMs and maxAgeMs. Arguments require commissioned productId; states is optional 1–3 unique red/unknown/green values; includeUnchanged is optional boolean. Original canonical argument values determine natural identity, including array order and omitted versus explicit defaults; a separate EV1 filter normalises execution semantics. HTTPS URLs are serialised by the URL parser, retaining the exact resulting private URL as identity. Userinfo, fragments, backslashes and control/space characters refuse. Secrets are canonical whsec_ base64 of 24–64 bytes.

Positive safe ttlMs is capped by policy; null/omitted gets the finite default. The original pending admission starts TTL. maxAgeMs 1–31 days is validated then ignored because replay is unavailable. Non-null well-formed cursor and unsupported delivery modes are typed Unsupported failures. unsubscribe identifies the authenticated principal plus exact name/arguments/canonical URL; optional mode webhook is a compatibility spelling. An absent own subscription returns {}; no ID/key/TTL/cursor is accepted. Current unsubscribe authority is required.

Each subscribe call is a fresh bounded renewal. Returned attempt is an internal recovery token, not an MCP parameter or bearer credential. Persist it privately if needed. reconcile requires current read authority and returns an immutable historical receipt plus current disposition; it performs no verification/renewal/reactivation. Missing/corrupt receipt within the fixed retry horizon remains unknown. At equality retry expires. inspect is host-only, read-authorised and redacted. No raw URL/key is returned. wireError accepts an approved refusal value or the narrowed state: 'refused' result returned by a host method, and never returns native exception text. Retained subscribe receipts must match the natural subscription ID, the original attempt/policy time bounds and any retained row of that exact epoch. Old receipts remain readable after renewal, unsubscribe or row cleanup; after row removal, the trusted store still owns the original grant fact, because the exact requested TTL/authority expiry is not separately retained.

Verification, rotation and finite cleanup

Pending admission atomically counts active/pending rows, checks capacities, reserves one fixed challenge slot and charges global/principal/callback fixed-minute buckets, including failures. A pending natural key refuses another challenge. Unknown slots survive TTL, rate-window ageing, private-row deletion and restart until actual terminal settlement or independently witnessed no-further-contact reconciliation. They can exhaust the finite allowance; no automatic timeout reclaim occurs.

The cache binds principal, canonical callback digest, key digest, store/policy and permissionGeneration. Cached refresh cannot extend its original expiry. Current generation drift forbids reuse. Unsubscribe conservatively removes the principal/callback cache across filters. Caller ACL revocation must invalidate affected cache under its same lock; retained generation comparison also prevents reuse. A genuinely new completed verification can replace an expired verification observation; it is not a cached refresh. Active predecessors keep their original grant during pending refresh. Rotation overlap starts only at the switch, is capped by the previous grant, and same-key refresh cannot extend it. Another different key during overlap refuses.

Call sweep with an independently authorised host-maintenance context even during quiet periods. Each call removes at most 32 due records; drain additional bounded calls within the commissioned retention deadline. Raw expired/stopped subscription material and expired old keys take priority; unknown effect slots retain opaque identity. cleanupInterval and retentionAfterExpiry are positive 1–60 seconds, with interval no greater than retention. Overdue cleanup refuses new subscribe/unsubscribe work before extending retention. Maintenance authority must remain current through required deletion, including after subscription policy expiry. Caller storage/backup policy owns physical deletion; no secure-erasure claim is made about JavaScript strings, port copies or forensic storage recovery.

Hard bounds include 16 KiB request/depth 16, 8 KiB public result, 256 KiB private root, 128 total/16 principal subscription rows, 256 attempts, 128 cache entries, 256 rate buckets, 8 total/2 principal unknown or pending challenges, and 64 global/8 principal/8 callback challenges per fixed 60 seconds. Policies can lower limits. Keys/URLs remain only in mutable private storage and trusted private ports, never immutable Journal, receipts, outbox, logs or public evidence. A caller unable to meet this contract is unqualified.

Source, installed consumer and fault acceptance are recorded separately; live host/receiver/public connector qualification, application delivery, broader supported hosts, CI and E36/EV3/EV4 remain open.

A passive first check

This executable example checks policy syntax and fixed error mapping without opening storage or contacting a receiver. Real subscription work requires the private transactional and connector obligations above; the package intentionally supplies no default store or network client.

import { parseSubscriptionPolicy, subscriptionPolicyDigest, wireError } from 'software-factory/provider-subscriptions';
const policy = parseSubscriptionPolicy({
  schema: 'sf-mcp-subscriptions-policy/1', id: 'host-policy', revision: 1,
  hostNamespace: 'my-host', store: 'private-store-a', productId: 'app',
  validUntil: '2026-12-01T00:00:00.000Z', defaultTtlMs: 60000, maxTtlMs: 300000,
  retryHorizonMs: 60000, portWaitMs: 3000, verificationTtlMs: 60000,
  rotationOverlapMs: 1000, challengeWindowMs: 60000,
  maxGlobalSubscriptions: 16, maxPrincipalSubscriptions: 4,
  maxGlobalPendingChallenges: 4, maxPrincipalPendingChallenges: 2,
  maxGlobalWindowChallenges: 16, maxPrincipalWindowChallenges: 8,
  maxCallbackWindowChallenges: 8, maxAttempts: 64, maxVerificationEntries: 16,
  maxChallengeWindows: 64, cleanupIntervalMs: 1000, retentionAfterExpiryMs: 2000,
});
if (!subscriptionPolicyDigest(policy).startsWith('sha256:')) throw Error('Policy digest missing');
const error = wireError({ code: 'unsupported', feature: 'cursor' });
console.log(error.message, error.data.feature);

The date is a static syntax example, not a currently commissioned grant. A real host supplies a current, authorised policy. The public HostOptions and PrivateRoot declarations are the complete adapter contract; the package does not silently bootstrap or recreate private state. A caller may retain an unknown fence indefinitely. Any external no-further-contact reconciliation must itself use the commissioned store/authority lock and an actual witness; there is no generic reconciliation endpoint or timeout-based release in this packet.

Native-data observation is separate from validation. Native Promise values under string or symbol data descriptors, including byte-view metadata, discarded late store results and malformed clock/nonce/store/connector returns, are observed while forbidden JSON remains refused; getters and user then methods are not invoked. Strict child-process proof covers refusal and uncertainty cases through two real private-store layouts, read/static refusals and a corrupted acknowledgement after a pending subscription commit. The latter retains the original uncertain attempt and starts no callback. Historical receipts and the previous accepted component remain unchanged.

Source: docs/how-to/adopt-provider-subscriptions.md