@wtfalch/edge 0.5.1 → 0.6.0

package/README.md

@@ -61,6 +61,17 @@ await edge.platform.tunnels.putConfig(tunnel.id, {
 const { token } = await edge.platform.tunnels.token(tunnel.id);
 ```
 
+```ts
+// With the platform credential only: an Access app and its policy
+const app = await edge.platform.access.create({ name: 'gate', domain: 'app.acme.com' });
+await edge.platform.access.createPolicy(app.id, {
+  name: 'staff',
+  decision: 'allow',
+  include: [{ email: { email: 'a@acme.com' } }],
+});
+const { token } = await edge.platform.access.findServiceToken('ci'); // id and name, never a secret
+```
+
 The key carries the organisation and the one domain its names live under, so
 no call names either. `claim` is safe to repeat: the same `ref` returns the same
 claim, and a new `port` moves its route. `get(ref)` finds the claim for a `ref` without listing. `close` makes the name answer 404 and

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type ClientOptions } from './transport.js';
-import type { AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AvailableResponse, ClaimNameRequest, CreatePlatformRecordRequest, CreatePlatformTunnelRequest, ListClaimsResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformRecordView, PlatformTunnelView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, TokenResponse, UpdatePlatformRecordRequest } from './types.js';
+import type { AdoptAccessAppsRequest, AdoptAccessAppsResponse, AdoptRecordsRequest, AdoptRecordsResponse, AdoptTunnelsRequest, AdoptTunnelsResponse, AvailableResponse, ClaimNameRequest, CreatePlatformAccessAppRequest, CreatePlatformAccessPolicyRequest, CreatePlatformRecordRequest, CreatePlatformTunnelRequest, FindServiceTokenResponse, ListClaimsResponse, ListPlatformAccessAppsRequest, ListPlatformAccessAppsResponse, ListPlatformAccessPoliciesResponse, ListPlatformRecordsRequest, ListPlatformRecordsResponse, ListPlatformTunnelsResponse, ListRecordsResponse, MintKeyRequest, MintKeyResponse, NameClaim, OrgSettingsRequest, PlatformAccessAppView, PlatformAccessPolicyView, PlatformRecordView, PlatformTunnelView, PutPlatformTunnelConfigRequest, RecordInput, RecordPatch, RecordView, TokenResponse, UpdatePlatformRecordRequest } from './types.js';
 export { EdgeApiError, type ClientOptions } from './transport.js';
 /** Called with an entry's key: the key carries its organisation and domain, so
  * no call names either. `setReservedLabels`, `mintKey` and `revokeKey` are
@@ -61,6 +61,30 @@ export declare function createEdgeClient(options: ClientOptions): {
              * or recreated, and a tunnel nobody names is left alone. */
             adopt: (input: AdoptTunnelsRequest) => Promise<AdoptTunnelsResponse>;
         };
+        /** Cloudflare Access applications the platform owns, and their policies.
+         * `id` is Cloudflare's app id. */
+        access: {
+            /** Every live app with its owner (`null`: no row), optionally narrowed
+             * by exact `domain` and/or `name`. */
+            list: (filter?: ListPlatformAccessAppsRequest) => Promise<ListPlatformAccessAppsResponse>;
+            /** Creates the app, or returns the one edge already made for that
+             * domain and name. Rejects with `conflict` when a live app holds the
+             * domain that nobody adopted (adopt it instead). */
+            create: (input: CreatePlatformAccessAppRequest) => Promise<PlatformAccessAppView>;
+            /** Deletes the app; returns the tombstone. Repeating it rejects with `not_found`. */
+            remove: (id: string) => Promise<PlatformAccessAppView>;
+            /** The policies on an app the platform owns. */
+            listPolicies: (appId: string) => Promise<ListPlatformAccessPoliciesResponse>;
+            /** Adds a policy. The same name with the same content returns it as it
+             * is (safe to repeat); the same name with other content rejects with `conflict`. */
+            createPolicy: (appId: string, input: CreatePlatformAccessPolicyRequest) => Promise<PlatformAccessPolicyView>;
+            /** A service token's id by exact name; `token` is `null` when none has
+             * it. Read-only: the secret is never returned. */
+            findServiceToken: (name: string) => Promise<FindServiceTokenResponse>;
+            /** Writes platform rows for the live apps named. Nothing is deleted or
+             * recreated, and an app nobody names is left alone. */
+            adopt: (input: AdoptAccessAppsRequest) => Promise<AdoptAccessAppsResponse>;
+        };
     };
     /** True when the name is free: not reserved, no record in the zone, not claimed. */
     available: (name: string) => Promise<AvailableResponse>;

package/dist/client.js

@@ -1,5 +1,9 @@
 import { createTransport } from './transport.js';
 export { EdgeApiError } from './transport.js';
+function query(values) {
+    const search = new URLSearchParams(Object.entries(values).filter((entry) => entry[1] !== undefined)).toString();
+    return search === '' ? '' : `?${search}`;
+}
 /** Called with an entry's key: the key carries its organisation and domain, so
  * no call names either. `setReservedLabels`, `mintKey` and `revokeKey` are
  * refused by the service for any credential but the platform's own. */
@@ -60,6 +64,30 @@ export function createEdgeClient(options) {
                  * or recreated, and a tunnel nobody names is left alone. */
                 adopt: (input) => call('POST', '/v1/platform/tunnels/adopt', input),
             },
+            /** Cloudflare Access applications the platform owns, and their policies.
+             * `id` is Cloudflare's app id. */
+            access: {
+                /** Every live app with its owner (`null`: no row), optionally narrowed
+                 * by exact `domain` and/or `name`. */
+                list: (filter = {}) => call('GET', `/v1/platform/access/apps${query(filter)}`),
+                /** Creates the app, or returns the one edge already made for that
+                 * domain and name. Rejects with `conflict` when a live app holds the
+                 * domain that nobody adopted (adopt it instead). */
+                create: (input) => call('POST', '/v1/platform/access/apps', input),
+                /** Deletes the app; returns the tombstone. Repeating it rejects with `not_found`. */
+                remove: (id) => call('DELETE', `/v1/platform/access/apps/${encodeURIComponent(id)}`),
+                /** The policies on an app the platform owns. */
+                listPolicies: (appId) => call('GET', `/v1/platform/access/apps/${encodeURIComponent(appId)}/policies`),
+                /** Adds a policy. The same name with the same content returns it as it
+                 * is (safe to repeat); the same name with other content rejects with `conflict`. */
+                createPolicy: (appId, input) => call('POST', `/v1/platform/access/apps/${encodeURIComponent(appId)}/policies`, input),
+                /** A service token's id by exact name; `token` is `null` when none has
+                 * it. Read-only: the secret is never returned. */
+                findServiceToken: (name) => call('GET', `/v1/platform/access/service-tokens?${new URLSearchParams({ name })}`),
+                /** Writes platform rows for the live apps named. Nothing is deleted or
+                 * recreated, and an app nobody names is left alone. */
+                adopt: (input) => call('POST', '/v1/platform/access/apps/adopt', input),
+            },
         },
         /** True when the name is free: not reserved, no record in the zone, not claimed. */
         available: (name) => call('GET', `/v1/names/available?${new URLSearchParams({ name })}`),

package/dist/types.d.ts

@@ -101,8 +101,9 @@ export interface OrgSettingsRequest {
  * soon. `pending`: still being set up. `removing`: teardown in progress, retry
  * the remove. `taken`: the name or ref belongs to something else; do not
  * retry. `held`: the name was removed less than 30 days ago; do not retry
- * until the hold ends. `upstream_rejected`: Cloudflare permanently refused; do not retry. */
-export type EdgeConflictReason = 'busy' | 'pending' | 'removing' | 'taken' | 'held' | 'upstream_rejected';
+ * until the hold ends. `exists`: a tunnel of that name already exists at
+ * Cloudflare; adopt it instead. `upstream_rejected`: Cloudflare permanently refused; do not retry. */
+export type EdgeConflictReason = 'busy' | 'pending' | 'removing' | 'taken' | 'held' | 'exists' | 'upstream_rejected';
 export type RecordType = 'TXT' | 'MX' | 'CNAME' | 'A' | 'AAAA' | 'CAA';
 /** CAA's structured value, in Cloudflare's form. */
 export interface CaaData {
@@ -269,6 +270,8 @@ export interface CreatePlatformTunnelRequest {
 /** One ingress rule. Every rule but the last names a hostname; the last is the catch-all. */
 export interface TunnelIngressRule {
     hostname?: string;
+    /** A regex Cloudflare matches against the request path, to tell rules on one hostname apart. */
+    path?: string;
     service: string;
     originRequest?: Record<string, unknown>;
 }
@@ -299,3 +302,93 @@ export interface AdoptTunnelsResponse {
     /** Live tunnels no entry named. Reported, never touched. */
     unclaimed: PlatformTunnelView[];
 }
+/** An Access application seen with the platform credential. `id` is Cloudflare's
+ * app id, which every platform Access call takes. */
+export interface PlatformAccessAppView {
+    id: string;
+    name: string;
+    domain: string;
+    /** Who owns it: the platform, or `null` when no row exists (a live app
+     * nobody adopted: reported, never touched). */
+    owner: 'platform' | null;
+    /** The company the app serves; `'platform'` when none. `null` for an app with no row. */
+    organisationId: string | null;
+    state: 'pending' | 'active' | 'removing' | 'removed';
+}
+export interface ListPlatformAccessAppsRequest {
+    /** Only the app on exactly this domain. */
+    domain?: string;
+    /** Only the apps with exactly this name. */
+    name?: string;
+}
+export interface ListPlatformAccessAppsResponse {
+    apps: PlatformAccessAppView[];
+}
+/** Creates the app, or returns the one edge already made for that domain and name. */
+export interface CreatePlatformAccessAppRequest {
+    name: string;
+    /** A lower-case hostname, optionally with a leading `*.`. */
+    domain: string;
+    /** Only `self_hosted` is supported (the default). */
+    type?: 'self_hosted';
+    /** Like `30m` or `24h`. */
+    sessionDuration?: string;
+    autoRedirectToIdentity?: boolean;
+    /** The company the app serves. Omit for an app that serves none. */
+    organisationId?: string;
+}
+/** One Access rule, in Cloudflare's own shape: `{ email: { email } }`, `{ everyone: {} }`, `{ service_token: { token_id } }`. */
+export type AccessRule = Record<string, unknown>;
+export type AccessDecision = 'allow' | 'deny' | 'non_identity' | 'bypass';
+export interface PlatformAccessPolicyView {
+    id: string;
+    name: string;
+    decision: AccessDecision;
+    include: AccessRule[];
+    exclude?: AccessRule[];
+    require?: AccessRule[];
+}
+export interface ListPlatformAccessPoliciesResponse {
+    policies: PlatformAccessPolicyView[];
+}
+/** Adds a policy to an app the platform owns. At least one `include` rule is required. */
+export interface CreatePlatformAccessPolicyRequest {
+    name: string;
+    decision: AccessDecision;
+    include: AccessRule[];
+    exclude?: AccessRule[];
+    require?: AccessRule[];
+}
+/** A service token's id and name. Its secret is never returned. */
+export interface FindServiceTokenResponse {
+    token: {
+        id: string;
+        name: string;
+    } | null;
+}
+export interface AdoptAccessAppEntry {
+    name: string;
+    /** Narrows several apps of one name. */
+    domain?: string;
+    /** Cloudflare's id, when the caller recorded it: the match must carry it. */
+    id?: string;
+}
+export interface AdoptAccessAppsRequest {
+    apps: AdoptAccessAppEntry[];
+    /** The company the adopted apps serve. Omit for none. */
+    organisationId?: string;
+}
+export interface AdoptAccessAppsResponse {
+    adopted: PlatformAccessAppView[];
+    alreadyAdopted: PlatformAccessAppView[];
+    /** `taken`: a row for that domain exists. `unsupported_type`: the app has
+     * no domain (not self-hosted). */
+    skipped: Array<{
+        app: PlatformAccessAppView;
+        reason: 'taken' | 'unsupported_type';
+    }>;
+    /** Entries with no live app. Nothing is created for them. */
+    notFound: AdoptAccessAppEntry[];
+    /** Live apps no entry named. Reported, never touched. */
+    unclaimed: PlatformAccessAppView[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/edge",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "description": "Public client SDK and API types for the edge service.",