@geostack/arc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GEOstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @geostack/arc
+
+Arc makes high-risk AI actions safe with permissions, approvals, signed execution, and audit.
+
+Arc does not run your app logic. Your app owns the action implementation. Arc verifies authority, asks for approval when policy requires it, signs the execution request, delivers it to your app, and records the audit trail.
+
+## Define Actions
+
+```ts
+import { arc } from "@geostack/arc";
+
+export const actions = arc.defineActions({
+  issue_refund: {
+    name: "Issue refund",
+    risk: "high",
+    defaultDecision: "ask",
+    input: {
+      type: "object",
+      required: ["amount", "customerId"],
+      properties: {
+        amount: { type: "number" },
+        customerId: { type: "string" }
+      }
+    }
+  }
+});
+```
+
+`risk` must be `low`, `medium`, or `high`. `defaultDecision` must be `allow`, `ask`, or `block`.
+
+## Handle Signed Execution
+
+```ts
+import express from "express";
+import { arc } from "@geostack/arc";
+import { actions } from "./actions.js";
+import { nonceStore } from "./arc-nonce-store.js";
+
+const app = express();
+app.use(express.json());
+
+app.post("/arc/execute", arc.handleAction(actions, {
+  issue_refund: async ({ input, appUserId, invocationId }) => {
+    // Enforce app-side idempotency by invocationId before side effects.
+    // Store the in-progress/completed record in durable storage shared by all app instances.
+    if (await refundAlreadyHandled(invocationId)) {
+      return getStoredRefundResult(invocationId);
+    }
+
+    return issueRefund(appUserId, input);
+  }
+}, {
+  apiUrl: "http://localhost:4000",
+  nonceStore
+}));
+```
+
+`handleAction()` verifies Arc's ES256 JWS, body hash, timestamp freshness, nonce replay hook, and signature claims before dispatching your handler.
+
+For lower-level integrations, call `verifyArcRequest(req, { jwks, nonceStore })` directly. The nonce store must return `false` for replayed nonces. Verification fails with `nonce_store_required` when no store is supplied.
+
+For production, use durable nonce replay storage shared by every app instance. The SDK's memory nonce store is a local development helper only and must be enabled explicitly with `unsafeAllowInMemoryNonceStore`. A production app that verifies without durable nonce storage is not safely integrated with Arc.
+
+Your app should also treat `invocation_id` as an idempotency key before performing side effects, because Arc may retry delivery after network failures or 5xx responses. A robust handler writes an idempotency row before the side effect and stores the final result when the side effect completes. If the process crashes after the app side effect but before Arc records success, Arc will mark the invocation outcome unknown rather than blindly retrying; your app's idempotency record is the source of truth for reconciliation.
+
+Minimal nonce store contract:
+
+```ts
+export const nonceStore = {
+  async useNonce(nonce: string, expiresAt: Date) {
+    // Atomically insert nonce with TTL. Return false when it already exists.
+    const result = await redis.set(`arc:nonce:${nonce}`, "1", {
+      NX: true,
+      PXAT: expiresAt.getTime()
+    });
+
+    return result === "OK";
+  }
+};
+```
+
+## Sync Actions
+
+```sh
+arc config set --api-url http://localhost:4000
+arc app create "Refund App" --execute-url http://host.docker.internal:8787/arc/execute
+arc actions sync ./src/actions.ts
+```
+
+The CLI stores local configuration in `~/.arc/config.json`. It never stores app API keys. Dev agent tokens are only stored when you create them with `arc agent dev-token`, and the CLI labels them as local development credentials.
+
+## Invoke Locally
+
+```sh
+arc agent dev-token
+arc invoke issue_refund --app refund-app --input '{"amount":480,"customerId":"cus_123"}'
+arc approvals list
+arc approvals approve <approval_id>
+arc audit tail
+```
+
+Allowed invocations are queued for signed delivery. Asked invocations create approvals. Blocked invocations never execute.
+
+## HTTP Clients
+
+```ts
+import { ArcDeveloperClient, ArcAgentClient } from "@geostack/arc";
+
+const developer = new ArcDeveloperClient({ baseUrl: "http://localhost:4000" });
+await developer.devLogin({ email: "dev@example.test" });
+
+const agent = new ArcAgentClient({
+  baseUrl: "http://localhost:4000",
+  agentToken: "arc_agent_..."
+});
+```
+
+The clients return Arc API JSON directly and throw `ArcHttpError` with `status`, `code`, and `message` for non-2xx responses.
+
+## Production Notes
+
+This SDK is V1 developer tooling, not a claim that the whole Arc stack is ready for public production traffic. Before public launch, run Arc with a production signing key, persistent app-side nonce storage, app-side idempotency by `invocation_id`, observability around failed/unknown executions, and network egress controls. The local Docker stack and committed development signing key are for local development only.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+type CliEnv = NodeJS.ProcessEnv;
+type CliIo = {
+    stderr: Pick<NodeJS.WriteStream, "write">;
+    stdout: Pick<NodeJS.WriteStream, "write">;
+};
+export declare function main(argv?: string[], env?: CliEnv, io?: CliIo): Promise<number>;
+export {};