@agimon-ai/po-vault 0.0.0-alpha.61

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

@@ -0,0 +1,57 @@
+# @agimon-ai/po-vault
+
+The one place Po keeps secrets: OAuth tokens, API keys and sign-in sessions, encrypted in the shared Po database.
+
+Po binds the vault as the global `po/vault` service on top of `po/db`. Every workspace and session resolves the same vault.
+
+## How it stores secrets
+
+- Each entry is an AES-256-GCM row in `vault_entries` inside `<po home>/db/po.sqlite`, with a fresh 12-byte IV and the namespace and key bound in as associated data. Nothing is written in plaintext.
+- One 32-byte data-encryption key protects every entry. It lives in the OS keyring (service `ai.agimon.po-vault`) when there is one, and otherwise in `<po home>/vault/key.bin`, an owner-only file. That file is the only thing in `<po home>/vault/`.
+- **File-key mode is obfuscation-grade.** On a host with no keyring, such as headless Linux, `key.bin` sits next to the database, so anyone who can read your home folder can read your secrets. `status().backend` reports `'file'` in that case.
+- If the key is lost while entries exist, the vault clears them and shows "Vault key was lost. Saved sign-ins were cleared; sign in again."
+
+## Trust
+
+Any in-process Po plugin can read any namespace. The vault keeps secrets off disk in plaintext; it does not isolate plugins from one another. It never logs, and it has no agent tool, code-mode namespace or skill.
+
+## API
+
+```ts
+import { PO_VAULT_CONTRACT, PO_VAULT_SERVICE, VaultError, type Vault } from '@agimon-ai/po-vault';
+
+const vault = context.get(PO_VAULT_SERVICE) as Vault;
+const saved = await vault.put('agiflow', 'global', { apiKey: 'k' });
+await vault.put('agiflow', 'global', { apiKey: 'k2' }, { expectRevision: saved.revision });
+const record = await vault.get('agiflow', 'global'); // { value, revision, updatedAt } or undefined
+await vault.delete('agiflow', 'global');
+```
+
+- `put` with `expectRevision: n` writes only when the stored revision is `n`; `null` writes only when there is no entry; omitted means last write wins. A mismatch throws `VaultError` with code `conflict`.
+- `withLock(namespace, key, op)` holds a cross-process lease while `op` runs, so it may span network calls such as a token refresh. The lease renews itself; if it is lost, the signal passed to `op` aborts. Write inside it with `put({ expectRevision })`.
+- Names: a namespace matches `^[a-z][a-z0-9.-]{0,63}$`, a key is 1 to 512 characters with no control characters, and a value is JSON of at most 64 KiB. Anything else throws code `invalid`.
+- Errors are `VaultError` with code `unavailable`, `invalid` or `conflict`. Messages are fixed per code and never carry a key, a value or an upstream cause.
+
+Declare the contract your root waits for, so a host without the vault shows a "waits for contract" notice instead of hanging:
+
+```ts
+export default defineRoot(createMyRoot, { inject: [PO_VAULT_CONTRACT] });
+```
+
+## Testing
+
+```ts
+import { createMemoryVault } from '@agimon-ai/po-vault/testing';
+
+const vault = createMemoryVault(); // same revision, conflict and lock rules, in memory
+```
+
+## Public API
+
+- `@agimon-ai/po-vault`: `PO_VAULT_SERVICE`, `PO_VAULT_CONTRACT`, `VAULT_KEYRING_SERVICE`, `VaultError`, and the `Vault`, `VaultRecord`, `VaultValue`, `VaultStatus`, `VaultErrorCode`, `VaultPutOptions`, `VaultDeleteOptions` types.
+- `@agimon-ai/po-vault/testing`: `createMemoryVault`.
+- `@agimon-ai/po-vault/extensions/server`: the native server entry, a fixed Po host package.
+
+## Requirements
+
+- Node.js 24 or newer

package/dist/apiContracts.cjs

@@ -0,0 +1,17 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region src/schemas/apiContracts.ts
+/** The vault is a Cordis service only: no HTTP route, socket, agent tool or command. */
+const apiContracts = (0, require("@agimon-ai/po-core/apiContracts").defineApiContract)({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["defineApiContract"],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** The vault is a Cordis service only: no HTTP route, socket, agent tool or command. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;;;;AAGA,MAAa,gBAAA,4CAAeA,CAAAA,CAAAA,kBAAAA,CAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,53 @@
+//#region src/schemas/apiContracts.d.ts
+/** The vault is a Cordis service only: no HTTP route, socket, agent tool or command. */
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+export { apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts"],"mappings":";;qBAGa"}

package/dist/apiContracts.mjs

@@ -0,0 +1,13 @@
+import { defineApiContract } from "@agimon-ai/po-core/apiContracts";
+//#region src/schemas/apiContracts.ts
+/** The vault is a Cordis service only: no HTTP route, socket, agent tool or command. */
+const apiContracts = defineApiContract({
+	version: 1,
+	http: [],
+	sockets: [],
+	dynamic: []
+});
+//#endregion
+export { apiContracts, apiContracts as default };
+
+//# sourceMappingURL=apiContracts.mjs.map

package/dist/apiContracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.mjs","names":[],"sources":["../src/schemas/apiContracts.ts"],"sourcesContent":["import { defineApiContract } from '@agimon-ai/po-core/apiContracts';\n\n/** The vault is a Cordis service only: no HTTP route, socket, agent tool or command. */\nexport const apiContracts = defineApiContract({ version: 1, http: [], sockets: [], dynamic: [] });\nexport default apiContracts;\n"],"mappings":";;;AAGA,MAAa,eAAe,kBAAkB;CAAE,SAAS;CAAG,MAAM,CAAC;CAAG,SAAS,CAAC;CAAG,SAAS,CAAC;AAAE,CAAC"}

package/dist/contracts-C6dCp2Il.mjs

@@ -0,0 +1,9 @@
+import { o as PO_VAULT_SERVICE } from "./vaultRules-B84nuLpN.mjs";
+import { defineServiceContract } from "@agimon-ai/po-core/extensionFile";
+//#region src/schemas/contracts.ts
+/** Bound once at the global level; every workspace and session resolves the same vault. */
+const PO_VAULT_CONTRACT = defineServiceContract(PO_VAULT_SERVICE, { scope: "global" });
+//#endregion
+export { PO_VAULT_CONTRACT as t };
+
+//# sourceMappingURL=contracts-C6dCp2Il.mjs.map

package/dist/contracts-C6dCp2Il.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts-C6dCp2Il.mjs","names":[],"sources":["../src/schemas/contracts.ts"],"sourcesContent":["import { defineServiceContract } from '@agimon-ai/po-core/extensionFile';\n\nimport { PO_VAULT_SERVICE } from '../constants/vault';\nimport type { Vault } from '../services/vault/type';\n\n/** Bound once at the global level; every workspace and session resolves the same vault. */\nexport const PO_VAULT_CONTRACT = defineServiceContract<Vault>(PO_VAULT_SERVICE, { scope: 'global' });\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'po/vault': Vault;\n  }\n}\n"],"mappings":";;;;AAMA,MAAa,oBAAoB,sBAA6B,kBAAkB,EAAE,OAAO,SAAS,CAAC"}

package/dist/contracts-Do7L_d_L.cjs

@@ -0,0 +1,13 @@
+const require_vaultRules = require("./vaultRules-CUudYo7G.cjs");
+//#region src/schemas/contracts.ts
+/** Bound once at the global level; every workspace and session resolves the same vault. */
+const PO_VAULT_CONTRACT = (0, require("@agimon-ai/po-core/extensionFile").defineServiceContract)(require_vaultRules.PO_VAULT_SERVICE, { scope: "global" });
+//#endregion
+Object.defineProperty(exports, "PO_VAULT_CONTRACT", {
+	enumerable: true,
+	get: function() {
+		return PO_VAULT_CONTRACT;
+	}
+});
+
+//# sourceMappingURL=contracts-Do7L_d_L.cjs.map

package/dist/contracts-Do7L_d_L.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts-Do7L_d_L.cjs","names":["defineServiceContract","PO_VAULT_SERVICE"],"sources":["../src/schemas/contracts.ts"],"sourcesContent":["import { defineServiceContract } from '@agimon-ai/po-core/extensionFile';\n\nimport { PO_VAULT_SERVICE } from '../constants/vault';\nimport type { Vault } from '../services/vault/type';\n\n/** Bound once at the global level; every workspace and session resolves the same vault. */\nexport const PO_VAULT_CONTRACT = defineServiceContract<Vault>(PO_VAULT_SERVICE, { scope: 'global' });\n\ndeclare module '@deepseek-ai/cordis' {\n  interface Context {\n    'po/vault': Vault;\n  }\n}\n"],"mappings":";;;AAMA,MAAa,qBAAA,6CAAoBA,CAAAA,CAAAA,sBAAAA,CAA6BC,mBAAAA,kBAAkB,EAAE,OAAO,SAAS,CAAC"}