@agimon-ai/po-network 0.0.0-stage → 0.0.2-alpha.0

package/LICENSE

@@ -0,0 +1,149 @@
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             Agimon Pty Ltd
+Licensed Work:        Po, the software in the Po source repository and the
+                      packages released from it, in each version released by
+                      the Licensor.
+                      The Licensed Work is (c) 2026 Agimon Pty Ltd.
+                      Material identified as third-party in the "Third-party
+                      components" section at the end of this file or in a
+                      NOTICE file, and any package or directory whose own
+                      license file grants a different license, is not part of
+                      the Licensed Work and remains under its own license.
+Additional Use Grant: You may make production use of the Licensed Work if
+  your use is Eligible Use. "Eligible Use" is production use that falls
+  within at least one of the following:
+
+  (a) Personal Use. Use by an individual for their own personal purposes,
+      and not on behalf of, or for the benefit of, an employer, client, or
+      other Organization. Use by an individual in the course of employment
+      or engagement by an Organization is use by that Organization.
+
+  (b) Small Organization Use. Use by or on behalf of an Organization whose
+      Annual Revenue is less than USD 1,000,000.
+
+  (c) Non-profit, Education and Research Use. Use, regardless of Annual
+      Revenue, by (i) an Organization registered or recognized as a
+      non-profit or charitable organization under the laws of its
+      jurisdiction, for its non-profit purposes; (ii) an accredited school,
+      college, or university, for teaching, learning, or academic research;
+      or (iii) a publicly funded research institution, for its research.
+
+  (d) Service Provider Use. Use by a consultant, contractor, agency, or other
+      service provider, regardless of its own Annual Revenue, solely to
+      build, deploy, host, operate, or support the Licensed Work for a client
+      whose own use would be Eligible Use under (a), (b), or (c). A service
+      provider's use for its own purposes is Eligible Use only if the service
+      provider itself qualifies under (b) or (c).
+
+
+  Hosted services. Offering the Licensed Work to third parties as a hosted
+  or managed service whose primary value is the Licensed Work is Eligible
+  Use only if each such third party's own use would be Eligible Use.
+
+  Definitions. "Organization" means any company, partnership, sole
+  proprietorship, trust, association, government body, or other entity, and
+  includes an individual acting in a business or professional capacity.
+  "Affiliate" means any entity that directly or indirectly controls, is
+  controlled by, or is under common control with an Organization, where
+  "control" means ownership of more than 50% of the voting interests of an
+  entity or the power to direct its management and policies by contract or
+  otherwise. "Annual Revenue" means the total gross revenue of an
+  Organization and all of its Affiliates combined, from all sources and
+  whether or not related to the Licensed Work, for its most recently
+  completed fiscal year, or, if it has not completed a fiscal year, for the
+  twelve months before the use (or since its formation, if shorter),
+  converted into US dollars at the average exchange rate for that period.
+  Proceeds of equity or debt financing are not revenue.
+
+  Threshold. If an Organization stops qualifying under (b), its existing
+  production use remains Eligible Use for 90 days after it stops
+  qualifying, after which it must obtain a commercial license or stop
+  production use. Use that was Eligible Use when it occurred never requires
+  a commercial license after the fact.
+Change Date:          Four years from the date a version of the Licensed Work
+                      is first publicly released by the Licensor.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please visit: https://agimon.ai/licensing
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# po-network
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Portable C6 roster admission, C9 election reducers, durable voter storage, a fixed
+operation router, ciphertext relay framing, and the deterministic election simulator.
+There are no direct Node imports in `src`. The existing po-web-security proof and
+sealed-channel adapters support Node and workerd with Node crypto compatibility.
+
+## C6 roster
+
+`initialRosterState(networkId)` seeds a network. `applyRoster(state, envelope,
+trust, now)` returns the next state, or `undefined` on any failed proof or shape.
+Use `signEnvelope(key, 'po/roster/v1', payload)` from po-web-security/deviceProof
+for snapshots, entries, and changes. Keys are base64url DER P-256 SPKI strings.
+The issuer signs the full snapshot. Each host entry needs a device locally pinned
+at that host for its owner. The trust callback must never trust keys in the incoming
+snapshot. Membership removal drops the person's hosts. Persist the returned state
+before publishing it and synchronously revoke channels when it becomes visible.
+Keep epoch and tombstones across restart. Equal epochs and rollback are refused;
+tombstoned host IDs cannot be reused.
+
+Voter changes and evictions require a network owner's pinned-device signature at
+the affected host. A changed voter flag must match both the signed entry and signed
+change. Term changes require the named voter host's roster key, with `signerKeyId`
+equal to its host ID. Terms strictly increase. `termChurnCount` counts observed
+signed term changes, while `termChurn` flags at least three changes within 60 seconds
+at the latest application. These are diagnostics, not extra votes or authority.
+C6 owner authorization is not C9 configuration commitment: voter reconfiguration
+must still pass the existing election quorum/change-certificate protocol. Do not
+replace an election state's voter roster directly from an owner signature.
+
+## Durability and fencing
+
+Open the database with the injected `po/sqlite` service at the composition root,
+then call `createSqliteElectionStorage(database, seed)`. The adapter stores the
+complete election state, including promises, accepted changes and the highest
+fence, in a network-keyed SQLite row. Use `transact` for existing pure election
+transitions and sign their results only after commit. Never delete this row or
+reseed it on restart. Storage errors propagate, never acknowledge them as success.
+
+Every coordinator mutation receiver must call `storage.mutate(network, lease,
+now, timing, verifyVote, effect)`. The fence and `effect(transaction)` commit in the
+same transaction. Use only the supplied transaction for SQL effects; do not re-enter
+the database or perform an external effect there. A failed effect rolls back both.
+A Worker may implement `ElectionStorage` with DO storage and run `admitMutation`
+inside the same transaction as its guarded effect. Verify votes using pinned epoch
+keys; a lease proves quorum, not application authorization.
+
+## Router and relay
+
+`createNetworkRouter` admits only `NETWORK_OPERATIONS`. Each typed handler supplies
+a shape validator, caller authorization, and implementation. Unknown operations,
+including object prototype names, fail closed. Mutation handlers must independently
+allowlist the destination operation and use durable fencing.
+
+`forwardNetworkFrame` routes `{ destinationHostId, sealed }` by host ID without
+keys or plaintext. Socket admission and availability are host composition concerns.
+`receiveNetworkFrame` takes an established nodeSealedChannel or async browser
+channel and a mandatory destination signed-request verifier (C3/C4 with durable
+nonces). It never treats decryption as authorization. Channel counters refuse
+replay and reordered-stale frames. Delayed frames still need current authorization
+and freshness at the destination. Reconnect with fresh authenticated channel keys;
+never reconstruct a channel with reset counters and reused keys. Never use
+sealedTransport's loopback plaintext pass-through for network traffic.
+
+## Liveness and limits
+
+One voter can self-elect. Two voters require both: losing either means no
+coordinator, so roster writes and coordinated relay service pause. Existing C6
+entries and direct roster-authorized peer links still serve authorized requests.
+A gateway can deny, delay or drop traffic, but cannot mint device proofs or decrypt
+sealed payloads. Relay destination and timing metadata remain visible.
+
+This is crash-fault-tolerant, **not Byzantine-safe**. Leases depend on bounded clock
+skew; receivers need durable fencing and atomic effects for safety. An owner cannot
+bypass an old quorum to recover a two-voter network safely. Runtime activation,
+roster synchronization, outbound WebSockets and Worker socket hibernation belong
+to host composition, not this library.
+
+`pnpm exec nx run-many -t lint,typecheck,build,test -p @agimon-ai/po-network --parallel=1`
+runs the election simulator through the package's normal `vitest --run` test target.
+
+### Retained roster changes
+
+Snapshots retain all signed evictions, the latest voter change per live host and current-epoch
+term records. Consumers verify retained signatures but apply effects only after their local epoch.
+This permits catch-up after a skipped eviction epoch and prevents old voter records authorizing a
+new flip. Evictions use owner pins without requiring a target host entry. An unverifiable eviction
+of a host absent locally and in the snapshot is skipped, so a newcomer can join. Such a newcomer
+has no tombstone for that host ID: a malicious issuer may later re-include an old device-signed
+entry. The issuer already orders records and may withhold changes. Independent local pins remain
+mandatory. Permanent eviction history requires a signed checkpoint before it can be compacted.
+
+Durable device host entries and owner voter/eviction decisions verify as of issuance, including on
+catch-up after their declared expiry. The fresh issuer snapshot supplies freshness. Term diagnostics
+still verify at the current time. Local pin revocation or rotation removes the old key's authority,
+so its old records stop verifying. A compromised still-pinned owner key can backdate records until
+it is unpinned; the issuer cannot correct a host's local trust decision.
+
+### Current membership ceiling
+
+ponytail: voter changes add or evict exactly one voter per owner-authorized slot. Owner changes and arbitrary voter-set replacement are unsupported; add them as new slot kinds. C6 enrollment alone never adds C9 votes.

package/dist/index.cjs

@@ -0,0 +1,62 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_election = require("./services/election.cjs");
+const require_roster = require("./services/roster.cjs");
+const require_durableElection = require("./services/durableElection.cjs");
+const require_router = require("./services/router.cjs");
+const require_relay = require("./services/relay.cjs");
+const require_capabilities = require("./services/capabilities.cjs");
+const require_configuration = require("./services/configuration.cjs");
+exports.CHANGE_PROMISE_TAG = require_election.CHANGE_PROMISE_TAG;
+exports.CHANGE_VOTE_TAG = require_election.CHANGE_VOTE_TAG;
+exports.EVICTION_TAG = require_election.EVICTION_TAG;
+exports.LEASE_TAG = require_election.LEASE_TAG;
+exports.NETWORK_ELECTION_TIMING = require_election.NETWORK_ELECTION_TIMING;
+exports.NETWORK_OPERATIONS = require_router.NETWORK_OPERATIONS;
+exports.VOTE_TAG = require_election.VOTE_TAG;
+exports.activateVoterChange = require_election.activateVoterChange;
+exports.admitMutation = require_election.admitMutation;
+exports.applyRoster = require_roster.applyRoster;
+exports.changePromiseFields = require_election.changePromiseFields;
+exports.changeVoteFields = require_election.changeVoteFields;
+exports.committedEpoch = require_configuration.committedEpoch;
+exports.committedVoters = require_configuration.committedVoters;
+exports.configurationValidators = require_configuration.configurationValidators;
+exports.consentCandidates = require_capabilities.consentCandidates;
+exports.createCapabilityDirectory = require_capabilities.createCapabilityDirectory;
+exports.createCapabilityManifest = require_capabilities.createCapabilityManifest;
+exports.createConfigurationService = require_configuration.createConfigurationService;
+exports.createNetworkRouter = require_router.createNetworkRouter;
+exports.createSqliteElectionStorage = require_durableElection.createSqliteElectionStorage;
+exports.deserializeElectionState = require_durableElection.deserializeElectionState;
+exports.effectiveProviders = require_capabilities.effectiveProviders;
+exports.evictVoter = require_election.evictVoter;
+exports.evictionFields = require_election.evictionFields;
+exports.fencingToken = require_election.fencingToken;
+exports.forwardNetworkFrame = require_relay.forwardNetworkFrame;
+exports.genesisVoters = require_configuration.genesisVoters;
+exports.grantVote = require_election.grantVote;
+exports.initialRosterState = require_roster.initialRosterState;
+exports.initialState = require_election.initialState;
+exports.isChangeBallot = require_configuration.isChangeBallot;
+exports.isChangeCertificate = require_configuration.isChangeCertificate;
+exports.isChangePromise = require_configuration.isChangePromise;
+exports.isChangeVote = require_configuration.isChangeVote;
+exports.isConfigurationAcceptInput = require_configuration.isConfigurationAcceptInput;
+exports.isConfigurationGenesisInput = require_configuration.isConfigurationGenesisInput;
+exports.isConfigurationHistoryInput = require_configuration.isConfigurationHistoryInput;
+exports.isConfigurationPromiseInput = require_configuration.isConfigurationPromiseInput;
+exports.isVoterAuthorization = require_configuration.isVoterAuthorization;
+exports.isVoterChange = require_configuration.isVoterChange;
+exports.prepareVoterChange = require_election.prepareVoterChange;
+exports.promiseVoterChange = require_election.promiseVoterChange;
+exports.quorum = require_election.quorum;
+exports.receiveNetworkFrame = require_relay.receiveNetworkFrame;
+exports.rosterAuthorityFresh = require_roster.rosterAuthorityFresh;
+exports.serializeElectionState = require_durableElection.serializeElectionState;
+exports.validCapabilityOperations = require_capabilities.validCapabilityOperations;
+exports.validLease = require_election.validLease;
+exports.validateConsentGrants = require_capabilities.validateConsentGrants;
+exports.verifyCapabilityManifest = require_capabilities.verifyCapabilityManifest;
+exports.verifyHostProof = require_relay.verifyHostProof;
+exports.voteFields = require_election.voteFields;
+exports.voterChangeFields = require_election.voterChangeFields;

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+import { Addition, CHANGE_PROMISE_TAG, CHANGE_VOTE_TAG, ChangeBallot, ChangeCertificate, ChangePromise, ChangeVote, EVICTION_TAG, ElectionState, ElectionStorage, Eviction, FencingToken, LEASE_TAG, Lease, NETWORK_ELECTION_TIMING, Proposal, Roster, Timing, Transition, VOTE_TAG, Vote, VoterAuthorization, VoterChange, activateVoterChange, admitMutation, changePromiseFields, changeVoteFields, evictVoter, evictionFields, fencingToken, grantVote, initialState, prepareVoterChange, promiseVoterChange, quorum, validLease, voteFields, voterChangeFields } from "./services/election.mjs";
+import { NetworkRosterState, RosterTrust, applyRoster, initialRosterState, rosterAuthorityFresh } from "./services/roster.mjs";
+import { NetworkDatabase, NetworkTransaction, createSqliteElectionStorage, deserializeElectionState, serializeElectionState } from "./services/durableElection.mjs";
+import { ConfigurationAcceptInput, ConfigurationHistoryInput, ConfigurationOperations, ConfigurationPorts, ConfigurationPromiseInput, ConfigurationService, committedEpoch, committedVoters, configurationValidators, createConfigurationService, genesisVoters, isChangeBallot, isChangeCertificate, isChangePromise, isChangeVote, isConfigurationAcceptInput, isConfigurationGenesisInput, isConfigurationHistoryInput, isConfigurationPromiseInput, isVoterAuthorization, isVoterChange } from "./services/configuration.mjs";
+import { NETWORK_OPERATIONS, NetworkOperation, NetworkOperationHandlers, NetworkOperations, createNetworkRouter } from "./services/router.mjs";
+import { NetworkHostProof, NetworkRelayFrame, forwardNetworkFrame, receiveNetworkFrame, verifyHostProof } from "./services/relay.mjs";
+import { CapabilityRoster, consentCandidates, createCapabilityDirectory, createCapabilityManifest, effectiveProviders, validCapabilityOperations, validateConsentGrants, verifyCapabilityManifest } from "./services/capabilities.mjs";
+export { Addition, CHANGE_PROMISE_TAG, CHANGE_VOTE_TAG, CapabilityRoster, ChangeBallot, ChangeCertificate, ChangePromise, ChangeVote, ConfigurationAcceptInput, ConfigurationHistoryInput, ConfigurationOperations, ConfigurationPorts, ConfigurationPromiseInput, ConfigurationService, EVICTION_TAG, ElectionState, ElectionStorage, Eviction, FencingToken, LEASE_TAG, Lease, NETWORK_ELECTION_TIMING, NETWORK_OPERATIONS, NetworkDatabase, NetworkHostProof, NetworkOperation, NetworkOperationHandlers, NetworkOperations, NetworkRelayFrame, NetworkRosterState, NetworkTransaction, Proposal, Roster, RosterTrust, Timing, Transition, VOTE_TAG, Vote, VoterAuthorization, VoterChange, activateVoterChange, admitMutation, applyRoster, changePromiseFields, changeVoteFields, committedEpoch, committedVoters, configurationValidators, consentCandidates, createCapabilityDirectory, createCapabilityManifest, createConfigurationService, createNetworkRouter, createSqliteElectionStorage, deserializeElectionState, effectiveProviders, evictVoter, evictionFields, fencingToken, forwardNetworkFrame, genesisVoters, grantVote, initialRosterState, initialState, isChangeBallot, isChangeCertificate, isChangePromise, isChangeVote, isConfigurationAcceptInput, isConfigurationGenesisInput, isConfigurationHistoryInput, isConfigurationPromiseInput, isVoterAuthorization, isVoterChange, prepareVoterChange, promiseVoterChange, quorum, receiveNetworkFrame, rosterAuthorityFresh, serializeElectionState, validCapabilityOperations, validLease, validateConsentGrants, verifyCapabilityManifest, verifyHostProof, voteFields, voterChangeFields };

package/dist/index.mjs

@@ -0,0 +1,8 @@
+import { CHANGE_PROMISE_TAG, CHANGE_VOTE_TAG, EVICTION_TAG, LEASE_TAG, NETWORK_ELECTION_TIMING, VOTE_TAG, activateVoterChange, admitMutation, changePromiseFields, changeVoteFields, evictVoter, evictionFields, fencingToken, grantVote, initialState, prepareVoterChange, promiseVoterChange, quorum, validLease, voteFields, voterChangeFields } from "./services/election.mjs";
+import { applyRoster, initialRosterState, rosterAuthorityFresh } from "./services/roster.mjs";
+import { createSqliteElectionStorage, deserializeElectionState, serializeElectionState } from "./services/durableElection.mjs";
+import { NETWORK_OPERATIONS, createNetworkRouter } from "./services/router.mjs";
+import { forwardNetworkFrame, receiveNetworkFrame, verifyHostProof } from "./services/relay.mjs";
+import { consentCandidates, createCapabilityDirectory, createCapabilityManifest, effectiveProviders, validCapabilityOperations, validateConsentGrants, verifyCapabilityManifest } from "./services/capabilities.mjs";
+import { committedEpoch, committedVoters, configurationValidators, createConfigurationService, genesisVoters, isChangeBallot, isChangeCertificate, isChangePromise, isChangeVote, isConfigurationAcceptInput, isConfigurationGenesisInput, isConfigurationHistoryInput, isConfigurationPromiseInput, isVoterAuthorization, isVoterChange } from "./services/configuration.mjs";
+export { CHANGE_PROMISE_TAG, CHANGE_VOTE_TAG, EVICTION_TAG, LEASE_TAG, NETWORK_ELECTION_TIMING, NETWORK_OPERATIONS, VOTE_TAG, activateVoterChange, admitMutation, applyRoster, changePromiseFields, changeVoteFields, committedEpoch, committedVoters, configurationValidators, consentCandidates, createCapabilityDirectory, createCapabilityManifest, createConfigurationService, createNetworkRouter, createSqliteElectionStorage, deserializeElectionState, effectiveProviders, evictVoter, evictionFields, fencingToken, forwardNetworkFrame, genesisVoters, grantVote, initialRosterState, initialState, isChangeBallot, isChangeCertificate, isChangePromise, isChangeVote, isConfigurationAcceptInput, isConfigurationGenesisInput, isConfigurationHistoryInput, isConfigurationPromiseInput, isVoterAuthorization, isVoterChange, prepareVoterChange, promiseVoterChange, quorum, receiveNetworkFrame, rosterAuthorityFresh, serializeElectionState, validCapabilityOperations, validLease, validateConsentGrants, verifyCapabilityManifest, verifyHostProof, voteFields, voterChangeFields };

package/dist/services/capabilities.cjs

@@ -0,0 +1,225 @@
+let _agimon_ai_po_core = require("@agimon-ai/po-core");
+let _agimon_ai_po_web_security_browser = require("@agimon-ai/po-web-security/browser");
+//#region src/services/capabilities.ts
+function record(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function text(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function fingerprint(value) {
+	return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+/** Shared allowlist shape check. Package builders log and drop invalid declarations. */
+function validCapabilityOperations(value) {
+	if (!Array.isArray(value) || value.length > 3) return false;
+	const scopes = /* @__PURE__ */ new Set();
+	return value.every((operation) => {
+		if (!record(operation) || ![
+			"global",
+			"workspace",
+			"session"
+		].includes(String(operation.scope))) return false;
+		const scope = String(operation.scope);
+		if (scopes.has(scope)) return false;
+		scopes.add(scope);
+		return Array.isArray(operation.names) && operation.names.length <= 64 && operation.names.every((name) => typeof name === "string" && /^[a-z][a-z0-9.-]{0,63}$/.test(name)) && new Set(operation.names).size === operation.names.length;
+	});
+}
+function createCapabilityManifest(input) {
+	return structuredClone({
+		hostId: input.hostId,
+		networkId: input.networkId,
+		packages: input.packages,
+		templates: input.templates,
+		issuedAt: input.now,
+		expiresAt: input.now + _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.manifest
+	});
+}
+/** Advisory only. Always binds the signature to the current roster key. */
+async function verifyCapabilityManifest(envelope, roster, now) {
+	try {
+		if (!record(envelope) || Object.keys(envelope).sort().join(",") !== "payload,signature,tag" || envelope.tag !== "po/capabilities/v1" || !record(envelope.payload) || typeof envelope.signature !== "string") return void 0;
+		const p = envelope.payload;
+		if (!text(p.hostId) || p.networkId !== roster.networkId || !Array.isArray(p.packages) || !Array.isArray(p.templates)) return void 0;
+		const host = roster.hosts.find((h) => h.hostId === p.hostId);
+		if (!host || ![
+			now,
+			p.issuedAt,
+			p.expiresAt
+		].every((v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0)) return void 0;
+		const payload = p;
+		if (payload.expiresAt <= payload.issuedAt || payload.expiresAt - payload.issuedAt > _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.manifest || payload.issuedAt > now + _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.clockSkew || now >= payload.expiresAt - _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.clockSkew || p.notBefore !== void 0 && (typeof p.notBefore !== "number" || !Number.isSafeInteger(p.notBefore) || p.notBefore < payload.issuedAt || p.notBefore >= payload.expiresAt || now < p.notBefore)) return void 0;
+		const names = /* @__PURE__ */ new Set();
+		for (const pkg of p.packages) {
+			if (!record(pkg) || !text(pkg.name) || names.has(pkg.name) || !text(pkg.version) || !fingerprint(pkg.contractFingerprint) || !validCapabilityOperations(pkg.operations)) return void 0;
+			names.add(pkg.name);
+		}
+		const ids = /* @__PURE__ */ new Set();
+		for (const template of p.templates) {
+			if (!record(template) || !text(template.id) || ids.has(template.id) || !fingerprint(template.fingerprint)) return void 0;
+			ids.add(template.id);
+		}
+		if (!await (0, _agimon_ai_po_web_security_browser.verifyAttestation)(host.publicKey, "po/capabilities/v1", (0, _agimon_ai_po_web_security_browser.federationEnvelopeFields)(payload), envelope.signature)) return void 0;
+		return structuredClone(payload);
+	} catch {
+		return;
+	}
+}
+function samePerson(a, b) {
+	return a.issuer === b.issuer && a.subject === b.subject;
+}
+/** Pure provider selection, never an operation authorization decision. */
+function effectiveProviders(input) {
+	const result = [];
+	const localNames = new Set(input.local?.packages.map((p) => p.name));
+	function add(hostId, manifest, packageName, provenance, consent) {
+		if (provenance !== "local" && localNames.has(packageName)) return;
+		const pkg = manifest?.packages.find((p) => p.name === packageName);
+		const reason = consent && input.now >= consent.expiresAt - _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.clockSkew ? "consent-expired" : !manifest || !pkg ? "manifest-missing" : input.now >= manifest.expiresAt - _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.clockSkew ? "manifest-expired" : void 0;
+		result.push({
+			hostId,
+			packageName,
+			version: pkg?.version ?? "",
+			operations: structuredClone(pkg?.operations ?? []),
+			provenance,
+			status: reason ? "unavailable" : "available",
+			...reason ? { reason } : {},
+			...manifest ? { expiresAt: manifest.expiresAt } : {}
+		});
+	}
+	for (const pkg of input.local?.packages ?? []) add(input.localHostId, input.local, pkg.name, "local");
+	for (const host of input.roster.hosts) {
+		if (host.hostId === input.localHostId) continue;
+		const manifest = input.manifests.get(host.hostId);
+		if (samePerson(host.owner, input.owner)) for (const pkg of manifest?.packages ?? []) add(host.hostId, manifest, pkg.name, "own");
+		else {
+			const consents = input.consents.filter((c) => c.workspaceId === input.workspaceId && c.providerHostId === host.hostId && samePerson(c.owner, input.owner));
+			const byPackage = /* @__PURE__ */ new Map();
+			for (const consent of consents) {
+				const previous = byPackage.get(consent.packageName);
+				if (!previous || consent.createdAt > previous.createdAt) byPackage.set(consent.packageName, consent);
+			}
+			for (const consent of byPackage.values()) add(host.hostId, manifest, consent.packageName, "consented", consent);
+		}
+	}
+	const rank = {
+		local: 0,
+		own: 1,
+		consented: 2
+	};
+	const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+	return result.sort((a, b) => rank[a.provenance] - rank[b.provenance] || compare(a.hostId, b.hostId) || compare(a.packageName, b.packageName));
+}
+/** Uses the same injected SQLite port as durable election, on Node or a DO. */
+async function createCapabilityDirectory(storage) {
+	await storage.exec("CREATE TABLE IF NOT EXISTS po_network_capabilities (network TEXT NOT NULL, host TEXT NOT NULL, issued_at INTEGER NOT NULL, envelope_json TEXT NOT NULL, PRIMARY KEY (network, host))");
+	return {
+		async publish(envelope, roster, now) {
+			const payload = await verifyCapabilityManifest(envelope, roster, now);
+			if (!payload) return false;
+			return storage.transaction(async (transaction) => {
+				const previous = await transaction.get("SELECT issued_at FROM po_network_capabilities WHERE network = ? AND host = ?", roster.networkId, payload.hostId);
+				if (previous && previous.issued_at >= payload.issuedAt) return false;
+				await transaction.run("INSERT OR REPLACE INTO po_network_capabilities (network, host, issued_at, envelope_json) VALUES (?, ?, ?, ?)", roster.networkId, payload.hostId, payload.issuedAt, JSON.stringify(envelope));
+				return true;
+			});
+		},
+		async read(roster, now) {
+			const rows = await storage.all("SELECT envelope_json FROM po_network_capabilities WHERE network = ? ORDER BY host", roster.networkId);
+			const result = [];
+			for (const row of rows) {
+				let envelope;
+				try {
+					envelope = JSON.parse(row.envelope_json);
+				} catch {
+					continue;
+				}
+				if (await verifyCapabilityManifest(envelope, roster, now)) result.push(envelope);
+			}
+			return result;
+		}
+	};
+}
+/** Signature, device pin, expected request scope and G8 freshness remain adapter checks. */
+function validateConsentGrants(grants, input) {
+	if (grants.length !== 2) return {
+		ok: false,
+		error: "invalid-grant-count"
+	};
+	const [first, second] = grants;
+	if (grants.some((g) => !g.constraints || g.constraints.package !== input.packageName)) return {
+		ok: false,
+		error: "package-mismatch"
+	};
+	if ([
+		"issuer",
+		"subject",
+		"networkId",
+		"deviceKeyId",
+		"callingHostId",
+		"targetHostId",
+		"workspaceId"
+	].some((field) => !text(first[field]) || first[field] !== second[field]) || grants.some((g) => g.redelegable !== false)) return {
+		ok: false,
+		error: "scope-mismatch"
+	};
+	const sets = [];
+	const used = /* @__PURE__ */ new Set();
+	for (const grant of grants) {
+		if (!Array.isArray(grant.operations) || !grant.operations.length || !Number.isSafeInteger(grant.expiresAt)) return {
+			ok: false,
+			error: "invalid-operations"
+		};
+		for (const name of grant.operations) {
+			if (!input.allowlist.includes(name) || used.has(name)) return {
+				ok: false,
+				error: "invalid-operations"
+			};
+			used.add(name);
+		}
+		const split = (0, _agimon_ai_po_core.splitConsentOperations)(grant.operations);
+		if (split.read.length && split.write.length) return {
+			ok: false,
+			error: "invalid-operations"
+		};
+		sets.push(split.read.length ? "read" : "write");
+	}
+	if (sets[0] === sets[1]) return {
+		ok: false,
+		error: "invalid-operations"
+	};
+	return {
+		ok: true,
+		expiresAt: Math.min(first.expiresAt, second.expiresAt)
+	};
+}
+/** Already verified manifests only; no UI or operation authority is conferred. */
+function consentCandidates(input) {
+	const result = [];
+	for (const host of input.roster.hosts) {
+		if (samePerson(host.owner, input.owner)) continue;
+		const manifest = input.manifests.get(host.hostId);
+		if (!manifest || input.now >= manifest.expiresAt - _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.clockSkew) continue;
+		for (const pkg of manifest.packages) {
+			const names = pkg.operations.find((o) => o.scope === "workspace")?.names;
+			if (!names?.length || input.consents.some((c) => c.workspaceId === input.workspaceId && c.providerHostId === host.hostId && c.packageName === pkg.name && samePerson(c.owner, input.owner) && input.now < c.expiresAt - _agimon_ai_po_web_security_browser.FEDERATION_FRESHNESS.clockSkew)) continue;
+			result.push({
+				hostId: host.hostId,
+				packageName: pkg.name,
+				version: pkg.version,
+				operations: [...new Set(names)].sort(),
+				manifestExpiresAt: manifest.expiresAt
+			});
+		}
+	}
+	return result.sort((a, b) => a.hostId < b.hostId ? -1 : a.hostId > b.hostId ? 1 : a.packageName < b.packageName ? -1 : a.packageName > b.packageName ? 1 : 0);
+}
+//#endregion
+exports.consentCandidates = consentCandidates;
+exports.createCapabilityDirectory = createCapabilityDirectory;
+exports.createCapabilityManifest = createCapabilityManifest;
+exports.effectiveProviders = effectiveProviders;
+exports.validCapabilityOperations = validCapabilityOperations;
+exports.validateConsentGrants = validateConsentGrants;
+exports.verifyCapabilityManifest = verifyCapabilityManifest;

package/dist/services/capabilities.d.mts

@@ -0,0 +1,69 @@
+import { NetworkDatabase } from "./durableElection.mjs";
+import { FederationCapabilities, FederationConsentCandidate, FederationEnvelope, FederationGrant, FederationPrincipal, FederationProvider, FederationProviderConsent } from "@agimon-ai/po-core";
+//#region src/services/capabilities.d.ts
+export interface CapabilityRoster {
+  networkId: string;
+  /** Current, non-evicted hosts only. */
+  hosts: {
+    hostId: string;
+    publicKey: string;
+  }[];
+}
+/** Shared allowlist shape check. Package builders log and drop invalid declarations. */
+export declare function validCapabilityOperations(value: unknown): value is FederationCapabilities['packages'][number]['operations'];
+export declare function createCapabilityManifest(input: {
+  hostId: string;
+  networkId: string;
+  packages: FederationCapabilities['packages'];
+  templates: FederationCapabilities['templates'];
+  now: number;
+}): FederationCapabilities;
+/** Advisory only. Always binds the signature to the current roster key. */
+export declare function verifyCapabilityManifest(envelope: unknown, roster: CapabilityRoster, now: number): Promise<FederationCapabilities | undefined>;
+/** Pure provider selection, never an operation authorization decision. */
+export declare function effectiveProviders(input: {
+  workspaceId: string;
+  owner: FederationPrincipal;
+  localHostId: string;
+  local: FederationCapabilities | undefined;
+  roster: {
+    hosts: {
+      hostId: string;
+      owner: FederationPrincipal;
+    }[];
+  };
+  manifests: ReadonlyMap<string, FederationCapabilities>;
+  consents: readonly FederationProviderConsent[];
+  now: number;
+}): FederationProvider[];
+/** Uses the same injected SQLite port as durable election, on Node or a DO. */
+export declare function createCapabilityDirectory(storage: NetworkDatabase): Promise<{
+  publish(envelope: unknown, roster: CapabilityRoster, now: number): Promise<boolean>;
+  read(roster: CapabilityRoster, now: number): Promise<FederationEnvelope<'po/capabilities/v1'>[]>;
+}>;
+/** Signature, device pin, expected request scope and G8 freshness remain adapter checks. */
+export declare function validateConsentGrants(grants: readonly FederationGrant[], input: {
+  packageName: string;
+  allowlist: readonly string[];
+}): {
+  ok: true;
+  expiresAt: number;
+} | {
+  ok: false;
+  error: 'invalid-grant-count' | 'invalid-operations' | 'scope-mismatch' | 'package-mismatch';
+};
+/** Already verified manifests only; no UI or operation authority is conferred. */
+export declare function consentCandidates(input: {
+  manifests: ReadonlyMap<string, FederationCapabilities>;
+  roster: {
+    hosts: {
+      hostId: string;
+      owner: FederationPrincipal;
+    }[];
+  };
+  consents: readonly FederationProviderConsent[];
+  workspaceId: string;
+  owner: FederationPrincipal;
+  now: number;
+}): FederationConsentCandidate[];
+//#endregion