@collective-intelligence/external-apps-server-sdk 0.1.3 → 0.1.5

package/README.md

@@ -427,6 +427,54 @@ succeeded before the new turn started count. A turn is
   subject, never with the application's scopes. Visitors are separate owners:
   one visitor never reads another visitor's conversation.
 
+## Messages
+
+`messages.send` sends one message through a messaging connection of the
+Organization, for example a Telegram bot or a WhatsApp Business Account. The
+application needs the `messaging:send` scope, and an administrator must grant
+the connection to the application on its administration page.
+
+```ts
+const sent = await ci.messages.send({
+  connectionId,
+  content: { kind: "text", text: "Your order is ready." },
+  idempotencyKey: `order-${orderId}-ready`,
+  organizationId,
+  target: { conversation, mode: "continue" }
+})
+// sent.value.result: { conversation, messageId }
+```
+
+- `target` continues a conversation with the Conversation Reference of an
+  earlier message (`{ mode: "continue", conversation }`), or starts one with
+  the recipient fields of the vendor (`{ mode: "start_new", recipient }`).
+- `content` is a text, or `{ kind: "voice", text, voice }` for a text that CI
+  speaks.
+- `sender` holds the sender fields of the vendor, for example
+  `{ phoneNumberId }`. It is required when the account has more than one
+  sender. `service` names the vendor service when the connection has more
+  than one.
+- The result is the Message Receipt: the message id of the vendor and the
+  Conversation Reference that continues the conversation. It means that the
+  vendor accepted the message, not that a person received it.
+- `idempotencyKey` (at most 256 characters; generated when omitted) makes a
+  repeat safe. A repeat with the same key and content returns the first
+  outcome and sends nothing. A repeat with the same key and other content
+  returns `conflict`. Use your own key when your server can repeat a send
+  after a crash.
+- CI sends once and never retries a failed send. A failed send returns
+  `message_send_failed` with a `sendErrorCode`, for example `window_closed`,
+  `recipient_unreachable`, `template_required` or `transport`. The same key
+  returns the same failure: use a new key to send again.
+- `send_outcome_unknown` means that the first send with the key has no
+  recorded outcome: it still runs, or CI stopped before it recorded the
+  outcome. CI does not send again for the key. Repeat the call later; if the
+  answer stays the same, check with the vendor before you send with a new key.
+- `not_found` means that the connection does not exist or is not granted to
+  the application. `rate_limited` (HTTP 429) means that the connection
+  reached its rate limit; it is retryable, and the client repeats it with the
+  same key.
+
 ## Member users
 
 A confidential application administers the `member` users of its own
@@ -503,11 +551,18 @@ const links = await ci.users.listCompanyLinks({ organizationId, userId })
 - A delegated user's `/application/v1/resources` and `knowledge_*` calls, and
   the Agents, Skills and workflows the user runs, carry the user's links to
   Knowledge policy as `subject.linkedCompanyIds`, and a policy reads the
-  entity id as `resource` path `["id"]`. To keep `member`-role users to their
-  own companies, declare a `deny` `filter` policy on the company schema: subject
-  match `user.role` equals `member`, rule "entity id not in
-  `linkedCompanyIds`". Gets and writes of any other company, creates included,
-  then fail with `forbidden` and lists omit it; other roles and service
+  entity id as `resource` path `["id"]`. CI also sets `subject.access`:
+  `"read"` for gets, lists, searches, facets, autocomplete, traversal and
+  retrieval, `"write"` for creates, updates, deletes and relation writes. The
+  operation sets it; a caller cannot. A policy that does not test `access`
+  applies to reads and writes alike.
+- To let `member`-role users write only their own companies but read every
+  company (for example through member-run Agents), declare a `deny` `filter`
+  policy on the company schema: subject match `user.role` equals `member` and
+  `access` equals `write`, rule "entity id not in `linkedCompanyIds`". Updates
+  and deletes of any other company, and creates, then fail with `forbidden`;
+  gets, lists and searches still return it. Without the `access` clause the
+  same policy also hides other companies from reads. Other roles and service
   credentials are unaffected.
 - The policy binds an execution only while it acts as the member. An Agent or
   Skill tool bound to a fixed user, or a workflow that runs as another user or
@@ -1124,6 +1179,12 @@ const auth = createFederatedAuth({
 })
 ```
 
+For local development, `applicationOrigin` and `issuer` also accept an `http`
+origin whose host is exactly `localhost`, a `127.0.0.0/8` address, or `[::1]`,
+for example `http://localhost:3000`. On such an origin the session cookie is
+`ci-federated`, without the `__Host-` prefix and the `Secure` attribute, which
+browsers do not accept over plain HTTP. Any other `http` origin is rejected.
+
 Each request uses its own URL origin. A request on an unlisted origin gets
 `400 invalid_request`, and session lookups on it return `null`. The `Origin`
 header, `returnTo` and logout checks compare with that request origin. Login
@@ -1145,6 +1206,89 @@ session lookup revalidates the short-lived CI identity. Revoked or expired CI
 access ends application authorization on the next validation. A confidential
 OAuth client may supply `clientSecret`; a public PKCE client omits it.
 
+### Configure from the CLI enrollment
+
+`ci apps enroll --env-file .env.local` writes the application's identity as
+`CI_ISSUER`, `CI_AUDIENCE`, `CI_APPLICATION_ID`, `CI_CLIENT_ID`,
+`CI_ORGANIZATION_ID`, `CI_SCOPES` and, for a confidential application,
+`CI_CLIENT_SECRET`. `readApplicationEnrollment` reads those variables, so the
+application names none of them. It throws a `TypeError` that lists every
+missing variable. Pass the same prefix as `--prefix` when it is not `CI_`.
+`ci apps env <application>` prints the same variables for an application that
+already exists, for example to copy them into a deployment pipeline; it leaves
+out `CI_CLIENT_SECRET`, which CI shows only once.
+
+```ts
+import {
+  createFederatedAuth,
+  readApplicationEnrollment
+} from "@collective-intelligence/external-apps-server-sdk/auth/federated"
+
+const enrollment = readApplicationEnrollment(process.env)
+export const auth = createFederatedAuth({
+  ...enrollment,
+  applicationOrigin: "http://localhost:3000",
+  session: { kind: "sealed_cookie", secrets: [sessionSecret] }
+})
+```
+
+Register `<applicationOrigin>/api/auth/callback` as the redirect URI:
+`ci apps enroll --redirect-uri http://localhost:3000/api/auth/callback ...`.
+
+### Read the session without a `Request`
+
+`getSession` and `getAccessToken` take a `Request`. Next.js Server Components
+and Server Functions have headers only. `sessionRequest` builds the request
+those reads need: it carries only the cookie, on the application origin.
+
+```ts
+import { sessionRequest } from "@collective-intelligence/external-apps-server-sdk/auth/federated"
+import { headers } from "next/headers"
+
+const accessToken = await auth.getAccessToken?.(
+  sessionRequest(await headers(), applicationOrigin)
+)
+```
+
+Mount `auth.handler` as the `GET` and `POST` handlers of
+`app/api/auth/[...path]/route.ts`.
+
+### Verify the access token in your own API
+
+When the application forwards the user's CI access token to a separate API as
+`Authorization: Bearer`, that API checks it with `createAccessTokenVerifier`.
+
+```ts
+import {
+  createAccessTokenVerifier,
+  FederatedAuthRejectedError,
+  readApplicationEnrollment
+} from "@collective-intelligence/external-apps-server-sdk/auth/federated"
+
+const tokens = createAccessTokenVerifier(readApplicationEnrollment(process.env))
+
+const caller = await tokens.verify(bearerToken)
+// userId, organizationId, applicationId, clientId, scopes, sessionId, expiresAt
+
+const identity = await tokens.identity(bearerToken, { signal: request.signal })
+// the same fields, and user { id, email, name }, roles, groupIds
+```
+
+- `verify` is offline against the issuer key set: ES256 signature, issuer,
+  audience, lifetime, and the application, client and Organization you supply.
+  It does not see a revocation before the token expires.
+- `identity` runs `verify`, then reads CI's current identity for the token and
+  checks that it describes the same grant. Use it when the API needs the
+  user's roles or groups, or must stop at once when CI revokes the token. It
+  is one CI request for each call, with a 10-second limit; cache the result
+  for as long as a role change may take to reach your API. Pass the `signal`
+  of the request you serve: when it aborts, the CI request ends and the call
+  rejects with the abort reason.
+
+Both throw `FederatedAuthRejectedError` for a token that is not valid for this
+application; answer `401`. Both throw `ApplicationUserAuthUnavailableError`
+when CI does not answer; answer `503`.
+
 ### Forwarding a bound entity to CI
 
 Import `defineCiEntityResource` from `/resources` and use it with the same

package/dist/admin.d.ts

@@ -4965,6 +4965,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 			description: string | null;
 			directChildCount: number;
 			directMemberCount: number;
+			fqn: string | null;
 			id: string;
 			inheritedMembershipImpact: {
 				descendantGroupCount: number;
@@ -4973,6 +4974,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 			};
 			name: string;
 			organizationId: string;
+			package: {
+				fqn: string;
+				managed: boolean;
+				readonly: boolean;
+			} | null;
 			parentGroupId: string | null;
 			parentPath: Array<{
 				id: string;
@@ -5001,6 +5007,7 @@ declare const createAdministrationApi: (client: Client$1) => {
 				description: string | null;
 				directChildCount: number;
 				directMemberCount: number;
+				fqn: string | null;
 				id: string;
 				inheritedMembershipImpact: {
 					descendantGroupCount: number;
@@ -5009,6 +5016,11 @@ declare const createAdministrationApi: (client: Client$1) => {
 				};
 				name: string;
 				organizationId: string;
+				package: {
+					fqn: string;
+					managed: boolean;
+					readonly: boolean;
+				} | null;
 				parentGroupId: string | null;
 				parentPath: Array<{
 					id: string;

package/dist/auth/federated.d.ts

@@ -57,6 +57,67 @@ export type UserAuthScopePolicy = Readonly<{
 	writeScope: string;
 }>;
 export type UserAuthAuthorization = (resourceId: string) => (request: Request, operation?: string) => Promise<EntityInvocationContext | Response>;
+export type CiFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type AccessTokenVerifierOptions = Readonly<{
+	/** CI External App id (`app_id` claim). Give this, `clientId`, or both. */
+	applicationId?: string;
+	audience: string;
+	/** OAuth client id (`client_id` claim). Give this, `applicationId`, or both. */
+	clientId?: string;
+	fetch?: CiFetch;
+	/** HTTPS CI issuer, or a loopback HTTP issuer for local development. */
+	issuer: string;
+	now?: () => number;
+	/** When set, a token of another Organization is rejected. */
+	organizationId?: string;
+}>;
+export type VerifiedAccessToken = Readonly<{
+	applicationId: string;
+	clientId: string;
+	expiresAt: Date;
+	organizationId: string;
+	scopes: readonly string[];
+	sessionId: string;
+	userId: string;
+}>;
+export type AccessTokenIdentity = VerifiedAccessToken & Readonly<{
+	/** Absent when CI supplies no current group policy for the application. */
+	groupIds: readonly string[] | undefined;
+	/** CI Organization roles; absent when CI supplies no current role policy. */
+	roles: readonly string[] | undefined;
+	user: Readonly<{
+		email: string | null;
+		id: string;
+		name: string | null;
+	}>;
+}>;
+export type AccessTokenVerifier = Readonly<{
+	/**
+	 * The token's current CI identity: `verify`, then CI's own answer for the
+	 * user, roles and groups. A token CI has revoked is rejected. Pass the
+	 * `signal` of the request being served: when it aborts, the CI request ends
+	 * and the call rejects with the abort reason.
+	 */
+	identity: (token: string, options?: Readonly<{
+		signal?: AbortSignal;
+	}>) => Promise<AccessTokenIdentity>;
+	/**
+	 * Offline check against the issuer key set. It does not see a revocation
+	 * before the token expires.
+	 */
+	verify: (token: string) => Promise<VerifiedAccessToken>;
+}>;
+/** The application's CI enrollment, as `ci apps enroll --env-file` writes it. */
+export type ApplicationEnrollment = Readonly<{
+	applicationId: string;
+	audience: string;
+	clientId: string;
+	/** Present for a confidential application only. */
+	clientSecret?: string;
+	issuer: string;
+	organizationId: string;
+	scopes: readonly string[];
+}>;
 declare class FederatedAuthRejectedError extends Error {
 	readonly code: "invalid_request" | "invalid_state" | "invalid_identity" | "authorization_failed";
 	constructor(code: FederatedAuthRejectedError["code"]);
@@ -104,6 +165,8 @@ export type FederatedAuthOptions = Readonly<{
 	/**
 	 * HTTPS browser-visible origin, or list of origins, that owns the auth routes and __Host cookie.
 	 * Each request uses its own listed origin; register `<origin><basePath>/callback` for each one.
+	 * A loopback HTTP origin such as `http://localhost:3000` is accepted for local development;
+	 * its cookie has no `__Host-` prefix and no `Secure` attribute.
 	 */
 	applicationOrigin: string | readonly string[];
 	audience: string;
@@ -125,8 +188,11 @@ declare const FederatedAuthRejectedError$1: typeof FederatedAuthRejectedError;
 type FederatedAuthRejectedError$1 = FederatedAuthRejectedError;
 declare const ApplicationUserAuthUnavailableError$2: typeof ApplicationUserAuthUnavailableError;
 export declare const authorizeWithUserAuth: (auth: Pick<ApplicationUserAuth, "getEntityContext">, policy: UserAuthScopePolicy) => UserAuthAuthorization;
+export declare const createAccessTokenVerifier: (options: AccessTokenVerifierOptions) => AccessTokenVerifier;
 export declare const createFederatedAuth: (options: FederatedAuthOptions) => ApplicationUserAuth;
 declare const FederatedAuthRejectedError$2: typeof FederatedAuthRejectedError;
+export declare const readApplicationEnrollment: (env: Readonly<Record<string, string | undefined>>, prefix?: string) => ApplicationEnrollment;
+export declare const sessionRequest: (headers: Headers, applicationOrigin: string) => Request;
 type ApplicationUserAuthUnavailableError$2 = ApplicationUserAuthUnavailableError$1;
 type FederatedAuthRejectedError$2 = FederatedAuthRejectedError$1;