Connecting Your Application to Alfiz Cloud: The Provider API

​

One contract, two implementations

1. The interface. AlfizProvider in @alfiz/core: the contract as a TypeScript type, what a Client attaches to.
2. The abstract class. AlfizProviderBase in @alfiz/core: the contract as an implementation root. Exactly two kinds of provider extend it, by design:
   • the local provider (AlfizApplication), the contract implemented against your database. Standalone, it is the org root: the complete system with no external dependency.
   • the hosted provider (HostedProvider), the same contract with its far side reached over the Provider API: an API connection wrapped in the abstract class. It stores and decides nothing itself; every operation is forwarded to the serving side, which enforces its own integrity rules on remote operations exactly as on local ones. Delegation, never a second writer.
3. The OpenAPI document. openapi/alfiz-provider.v1.yaml, shipped in the @alfiz/core package: the contract’s wire form, fixed as a language-agnostic document rather than a TypeScript export.

​

The wire, in five conventions

• Every operation is POST {base}/v1/{op} with a JSON object body of the operation’s named parameters ({} when there are none). POST-only keeps the transport uniform and keeps authorization data out of URLs and shared caches.
• Every success is a 200 with a JSON object, never a bare array or primitive or null, so any response can grow a field without a wire break. Void operations return {}.
• Every failure carries a typed-error envelope under a non-2xx status. The status is a transport hint, and a correct one, so retry policies and dashboards read the API sensibly (403 not org root, 409 conflict or graph cycle, 422 validation, 404 not found, 501 unsupported), but the envelope is normative. ProviderWriteRejectedError codes and GraphCycleError paths survive the wire and re-throw intact on the calling side, so a dashboard renders “cycle: a → b → a” identically for local and remote writes.
• Authentication is Authorization: Bearer <token>, the secret minted at link time, compared in constant time.
• The live onInvalidate stream never crosses. The epoch operations (epoch.head, epoch.since) are the cross-process invalidation transport, exactly the mechanism the library already uses between processes sharing a database, carried over HTTP instead.

​

The non-JS check path: POST /v1/check

curl -s -X POST "$ALFIZ_BASE/v1/check" \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{
    "principal": { "userId": "u_42" },
    "key": ["docs.files.read", "docs.admin.read"],
    "scope": "docs.doc:123",
    "fresh": false
  }'
# → { "allowed": true }

​

Mount the handler

import { createProviderHandler } from "@alfiz/application";
import { app, storage } from "@/authz/app";

export const POST = createProviderHandler({
  application: app,
  storage,
  secret: process.env.ALFIZ_PROVIDER_SECRET!,
  applicationId: "docs",
});

​

Set up the connection

​

Handling authority transfer

import { createProviderHandler } from "@alfiz/application";
import { getApp, rebuildApp, storage } from "@/authz/app";

export const POST = createProviderHandler({
  application: getApp(),
  storage,
  secret: process.env.ALFIZ_PROVIDER_SECRET!,
  applicationId: "docs",
  onAuthorityChanged: async (orgRoot) => {
    // Reconstruct the Application with the new orgRoot value.
    // `false` after promotion (Alfiz Cloud is now the org root);
    // `true` after demotion (your Application resumes authority).
    await rebuildApp({ orgRoot });
  },
});

​

Consuming the API yourself

import { createHostedProvider } from "@alfiz/application";

const provider = createHostedProvider({
  url: "https://internal.example.com/api/alfiz", // ops POST to {url}/v1/{op}
  secret: process.env.ALFIZ_PROVIDER_SECRET!,
});

await provider.listRequests({ state: "pending" }); // enforced by the far side

​

Next steps