@collective-intelligence/external-apps-server-sdk 0.1.1 → 0.1.2

package/README.md

@@ -27,8 +27,10 @@ subpaths:
 The SDK has three separate authentication boundaries:
 
 - `createServerClient` uses confidential service credentials for requests from
-  the customer server to CI. Keep those credentials on the server and use the
-  only supported client mode, `service`. Its `tenantUrl` must be a
+  the customer server to CI. Keep those credentials on the server and use
+  client mode `service`, or delegated mode with a member access token from
+  [`exchangeMemberSession`](#call-ci-as-a-member-your-server-signed-in) to act
+  as a member. Its `tenantUrl` must be a
   credential-free HTTPS origin; for local development it also accepts an
   `http` origin whose host is exactly `localhost`, a `127.0.0.0/8` address, or
   `[::1]`. Any other `http` host is rejected before credentials are sent.
@@ -45,8 +47,8 @@ through `/admin`. None of these credentials or grants belongs in a Gateway
 manifest.
 
 A confidential application created by package install has no `clientSecret`
-until an administrator with `public_applications:manage` rotates its credential
-(`POST /admin/organization/public-applications/{id}/credential/rotate`, or
+until an administrator with `external_apps:manage` rotates its credential
+(`POST /admin/organization/external-apps/{id}/credential/rotate`, or
 **Rotate secret** in the Dashboard). CI returns the secret once; store it
 server-side. See
 [Provision a secret for a package-created application](../../../docs/reference/package-release-cli.md#provision-a-secret-for-a-package-created-application).
@@ -135,6 +137,61 @@ Override `validate`, `idempotencyKey`, `authorize`, or `getAccessToken` when
 the application needs different policy. The deprecated `./express` entry
 re-exports only `createGatewayExpressMiddleware` from `./runtime/express`.
 
+## Call CI as a member your server signed in
+
+A server that signs members in to CI itself (for example through
+`POST /auth/otp/verify`) holds each member's CI session token. CI application
+APIs do not accept that session token. Exchange it for a short-lived member
+access token with `exchangeMemberSession`, then call CI through a delegated
+`createServerClient`:
+
+```ts
+import {
+  createServerClient,
+  exchangeMemberSession,
+  MemberSessionExchangeError
+} from "@collective-intelligence/external-apps-server-sdk"
+
+const { accessToken, expiresAt } = await exchangeMemberSession({
+  credentials: { clientId, clientSecret },
+  organizationId,
+  scopes: ["context:read", "knowledge:write"],
+  sessionToken: member.ciSessionToken,
+  tenantUrl: "https://ci.example.com"
+})
+const ci = createServerClient({
+  authentication: { getAccessToken: () => accessToken },
+  tenantUrl: "https://ci.example.com"
+})
+await ci.context.get({ organizationId })
+```
+
+Only a confidential application can exchange, with its client secret. CI
+applies the same checks as the browser login: the session is live, the member
+is not banned and belongs to the Organization, the application is enabled and
+allowed in that Organization, and the requested scopes are a non-empty subset
+of the application's scopes. The token acts as the member (`detached_user`),
+lasts 300 seconds, has no refresh token, and stops working when the member's
+CI session ends. `expiresAt` is counted from before the request and set 30
+seconds early, so exchange again once it passes; never send either token to
+the browser.
+
+The request and its response body are bounded by `timeoutMs` (10 seconds by
+default); a CI that stops answering ends in `temporarily_unavailable`. Pass
+`signal` to cancel: a cancelled exchange rejects with the signal's reason, never
+with a retryable `MemberSessionExchangeError`.
+
+A refusal throws `MemberSessionExchangeError`. `code` is CI's OAuth error:
+`invalid_grant` means the CI session ended or the member cannot act in the
+Organization, so sign the member in again. `invalid_client`,
+`unauthorized_client`, `invalid_scope` and `invalid_target` point at the
+application's credentials, type, scopes or allowed Organizations.
+`temporarily_unavailable` is retryable. On the wire this is the RFC 8693 grant
+`urn:ietf:params:oauth:grant-type:token-exchange` on `POST /oauth/token`, with
+`subject_token_type`
+`urn:collective-intelligence:params:oauth:token-type:session_token`, `scope`
+and `organization_id`.
+
 ## Reuse Nest operations and local AI tools
 
 Use Node 22+ with ESM for the AI SDK 7 adapter. The inspected and tested baseline on 6 October 2026
@@ -359,8 +416,7 @@ succeeded before the new turn started count. A turn is
   retried message replay the same turn instead of adding one. Use each key for
   one message only; reusing it for a different message or conversation returns
   `conflict`.
-- The application's Agent capability gates conversations, with the `ai:invoke`
-  scope.
+- The `ai:invoke` scope gates conversations.
 - The Agent's current audience gates every turn and every `history` read. When
   an administrator removes the caller from the audience, the same caller gets
   `not_found` for its own conversations too.
@@ -371,6 +427,94 @@ 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.
 
+## Member users
+
+A confidential application administers the `member` users of its own
+Organization: people whose only role there is `member` (Organization identity
+and their own Knowledge; no CI Studio or dashboard). The Organization is the
+one the credentials were authorized for through `organizationId`; a request
+cannot reach another Organization.
+
+```ts
+const ci = createServerClient({
+  authentication: { credentials, mode: "service" },
+  tenantUrl
+})
+
+const created = await ci.members.createOrGet({
+  email: "info@rossi.example",
+  name: "Rossi Srl",
+  organizationId
+})
+// created.value.result: { userId, email, name, outcome }
+```
+
+- `createOrGet` resolves an email to one member user. `outcome` is `created`
+  for a new CI user, `linked` when an existing CI user joined the Organization
+  as a member, and `existing` when the user already was one. The email is
+  matched ignoring letter case, and concurrent or retried calls return the
+  same `userId`. It never sends CI's activation invitation and never accepts
+  a pending Organization invitation for the email; the application owns
+  onboarding.
+- `get({ userId })`, `list({ page?, pageSize? })` (at most 100 per page),
+  `update({ userId, name })` and `remove({ userId })` act only on member users.
+  `update` changes the name only of a user who belongs to no other
+  Organization. `remove` ends the `member` membership and keeps the CI user.
+- A user who holds any other role in the Organization (an administrator, for
+  example) is refused with `conflict` by every operation. `get`, `update` and
+  `remove` answer `not_found` for a user who is not in the Organization.
+- Reads need the `members:read` scope and writes `members:write`. Only service
+  credentials may call them: a delegated user token or an anonymous visitor
+  gets `operation_not_allowed`.
+- Only `temporarily_unavailable` is retryable (the client retries it); a
+  creation CI refuses is a non-retryable `internal_error`.
+
+## Member company links
+
+An application links a member of its Organization to the Knowledge company
+entities the member acts for. A member can have several companies and a company
+several members.
+
+```ts
+const linked = await ci.users.linkCompanies({
+  entityIds: [companyEntityId],
+  organizationId,
+  userId
+})
+// linked.value.result: { entityIds } — all of the user's links
+
+const links = await ci.users.listCompanyLinks({ organizationId, userId })
+```
+
+- Only confidential service credentials may call these operations: a delegated
+  user token or an anonymous visitor gets `operation_not_allowed`, and the
+  browser client and user proxy do not offer them.
+- The Organization is the caller's. A user without membership in it, or an
+  entity that is missing, deleted, or in another Organization, returns
+  `not_found`; a refused call links nothing.
+- Linking keeps existing links, so a retried call converges. Results list the
+  user's linked entities in entity id order.
+- `knowledge:write` gates `linkCompanies`; `knowledge:read` gates
+  `listCompanyLinks`.
+- CI accepts any entity of the Organization and does not check its schema; the
+  calling application decides which entities count as companies.
+- Entity deduplication moves links to the surviving entity; physically deleting
+  an entity removes its links.
+- 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
+  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
+  a service principal, decides as that principal, not as the member who
+  invoked it. Do not give Agents or workflows that members can reach a
+  fixed-user or run-as identity with wider Knowledge access.
+
 ## Gateway registry and orchestration
 
 Build one registry with `defineGateway`. Its `knowledge`, `datasets`, and
@@ -885,7 +1029,7 @@ const handle = createResourceHttpHandler({
 
 `auth` is the existing `createFederatedAuth(...)` instance. Its server-only
 `getEntityContext` resolves current CI application, user, organization, scopes,
-roles and team IDs; browser session JSON remains identity and expiry only.
+roles and group IDs; browser session JSON remains identity and expiry only.
 Missing CI policy context denies entity access. Local Better Auth sessions do
 not establish CI entity authority. Browser framework adapters require this
 verified context instead of boolean authorization. Machine gateway calls retain
@@ -965,6 +1109,36 @@ browser-visible HTTPS application origin, CI issuer, OAuth client, organization,
 audience, scopes, and an application-owned atomic session store. The facade owns
 PKCE login, callback, session inspection and logout under `/api/auth` by default.
 
+`applicationOrigin` accepts one HTTPS origin or a list. Use a list when one
+server answers on several domains with one CI Client ID:
+
+```ts
+const auth = createFederatedAuth({
+  applicationOrigin: ["https://app.acme.com", "https://app.acme.it"],
+  audience,
+  clientId,
+  issuer,
+  organizationId,
+  scopes: ["knowledge:read"],
+  session: { kind: "sealed_cookie", secrets }
+})
+```
+
+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
+and the token exchange both send `redirect_uri = <origin><basePath>/callback`.
+The pending login lives in a host-only cookie, so the callback arrives on the
+origin that started the login. The browser cannot choose the callback through a
+query parameter or header.
+
+On the CI application, register every callback, for example
+`https://app.acme.com/api/auth/callback` and
+`https://app.acme.it/api/auth/callback`, with `ci apps redirect-uris add`.
+Add every origin as a trusted website with `ci apps origins add`. CI binds the
+authorization code to its `redirect_uri`, so an unregistered callback fails at
+authorization.
+
 The store persists only hashed opaque-cookie state, token grants and revisions;
 the browser receives a `Secure`, `HttpOnly`, `SameSite=Lax` host cookie. Every
 session lookup revalidates the short-lived CI identity. Revoked or expired CI