@collective-intelligence/external-apps-server-sdk 0.2.2 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +6 -0
- package/README.md +189 -80
- package/dist/admin.d.ts +85 -98
- package/dist/admin.js +2 -2
- package/dist/auth/better-auth.d.ts +15 -6
- package/dist/auth/federated.d.ts +70 -22
- package/dist/auth/federated.js +1 -1
- package/dist/auth.d.ts +7 -5
- package/dist/chunks/{index-qe1587f9.js → index-7pww93nd.js} +4 -4
- package/dist/effect.d.ts +78 -196
- package/dist/effect.js +1 -1
- package/dist/index.d.ts +1457 -251
- package/dist/index.js +1 -1
- package/dist/next.d.ts +24 -13
- package/dist/next.js +1 -1
- package/dist/persistence/drizzle.d.ts +6 -5
- package/dist/resources.d.ts +7 -5
- package/dist/resources.js +1 -1
- package/dist/runtime/nestjs.d.ts +6 -6
- package/dist/runtime/web.d.ts +24 -13
- package/dist/runtime/web.js +1 -1
- package/docs/effect.md +14 -6
- package/docs/next-cache.md +5 -0
- package/package.json +4 -4
package/AGENTS.md
CHANGED
|
@@ -19,6 +19,12 @@ Primitives, the Revalidate Route and the Effect services. The package
|
|
|
19
19
|
- Let SDK writes expire their tags: pass `invalidate: nextInvalidate`, or merge
|
|
20
20
|
`CacheInvalidation.layerNext` into the runtime. Keep `revalidateTag` for
|
|
21
21
|
writes that do not go through the SDK.
|
|
22
|
+
- Read CI records with `resources.records.get` and `search` (`ServerClient`
|
|
23
|
+
`records.get` and `search` in `/effect`). `knowledge.getEntity` and
|
|
24
|
+
`searchEntities` reject with `TypeError`.
|
|
25
|
+
- In an Effect server that calls CI as each member, build one
|
|
26
|
+
`layerDelegatedServerClient` for the app and provide the member token per
|
|
27
|
+
request as `DelegatedAccessToken`. Do not build a client per token.
|
|
22
28
|
- Mount the Revalidate Route next to the ticket route, with the same
|
|
23
29
|
`secrets`.
|
|
24
30
|
- Branch on an error by its class (`instanceof`, `Effect.catchTag`) and its
|
package/README.md
CHANGED
|
@@ -169,7 +169,9 @@ path, query, or fragment. Mount `createExternalApplicationBff` (or
|
|
|
169
169
|
`createExternalApplicationBffNextHandlers`) once for federated auth, Resource
|
|
170
170
|
proxy, and dedicated Capability forwarding. Pass `ciResources` to bind one
|
|
171
171
|
Resource proxy mount per entity contract by `schemaFqn`; the BFF authorizes
|
|
172
|
-
those mounts with `authorizeWithUserAuth
|
|
172
|
+
those mounts with `authorizeWithUserAuth`, whose `read` and `write` Access
|
|
173
|
+
Requirements are checked against the app's slice of the user's access
|
|
174
|
+
(default: `core.platform.knowledge` for both; CI decides each record again). Dedicated Capability forwarding sends
|
|
173
175
|
the signed-in user's delegated token and the caller's `x-organization-id` by
|
|
174
176
|
default. For an application without federated CI users, pass
|
|
175
177
|
`capabilities: { authentication: { mode: "service", credentials },
|
|
@@ -184,10 +186,15 @@ so the backend runs only the Agent's own bindings and never the application's
|
|
|
184
186
|
service authority. An Audit subject with `mappedUserId` is refused with `401`
|
|
185
187
|
for a visitor caller. Forwarding covers `context`, `knowledge`, `agents`,
|
|
186
188
|
`conversations` (continue and history), `skills`, `workflows`, and `runs/*`.
|
|
189
|
+
In user-token mode, and for each `ciResources` mount, the BFF passes CI's
|
|
190
|
+
answer to `auth.observeCiResponse`: a `401` or a changed `x-access-version`
|
|
191
|
+
drops the identity that lookups of that Access token reuse, so the next
|
|
192
|
+
lookup reads CI again at once.
|
|
187
193
|
Reconstruct the public origin from
|
|
188
194
|
`x-forwarded-host` / `x-forwarded-proto`. Compose a Fixed workflow route with
|
|
189
195
|
`createFixedWorkflowRoute`: it rewrites that public origin, authorizes
|
|
190
|
-
`getEntityContext` plus
|
|
196
|
+
`getEntityContext` plus an optional `requirement` (an Access Requirement on
|
|
197
|
+
the app's slice of the user's access), stamps `x-organization-id` from the
|
|
191
198
|
session, POSTs `/application/v1/workflows/:id/runs`, and returns `{ runId }`.
|
|
192
199
|
Configure exactly one server-owned target: `workflowId` for a workflow UUID or
|
|
193
200
|
`workflowFqn` for its stable fully qualified name. The route rejects either
|
|
@@ -214,7 +221,6 @@ import {
|
|
|
214
221
|
const { accessToken, expiresAt } = await exchangeMemberSession({
|
|
215
222
|
credentials: { clientId, clientSecret },
|
|
216
223
|
organizationId,
|
|
217
|
-
scopes: ["context:read", "knowledge:write"],
|
|
218
224
|
sessionToken: member.ciSessionToken,
|
|
219
225
|
tenantUrl: "https://ci.example.com"
|
|
220
226
|
})
|
|
@@ -228,8 +234,9 @@ await ci.context.get({ organizationId })
|
|
|
228
234
|
Only a confidential application can exchange, with its client secret. CI
|
|
229
235
|
applies the same checks as the browser login: the session is live, the member
|
|
230
236
|
is not banned and belongs to the Organization, the application is enabled and
|
|
231
|
-
allowed in that Organization, and the
|
|
232
|
-
|
|
237
|
+
allowed in that Organization, and the member enters the app: one of its grants
|
|
238
|
+
holds the app gate. The token acts as the member (`detached_user`), cut to the
|
|
239
|
+
app's Max Privileges,
|
|
233
240
|
lasts 300 seconds, has no refresh token, and stops working when the member's
|
|
234
241
|
CI session ends. `expiresAt` is counted from before the request and set 30
|
|
235
242
|
seconds early, so exchange again once it passes; never send either token to
|
|
@@ -243,13 +250,13 @@ with a retryable `MemberSessionExchangeError`.
|
|
|
243
250
|
A refusal throws `MemberSessionExchangeError`. `code` is CI's OAuth error:
|
|
244
251
|
`invalid_grant` means the CI session ended or the member cannot act in the
|
|
245
252
|
Organization, so sign the member in again. `invalid_client`,
|
|
246
|
-
`unauthorized_client
|
|
247
|
-
|
|
253
|
+
`unauthorized_client` and `invalid_target` point at the application's
|
|
254
|
+
credentials, type or allowed Organizations.
|
|
248
255
|
`temporarily_unavailable` is retryable. On the wire this is the RFC 8693 grant
|
|
249
256
|
`urn:ietf:params:oauth:grant-type:token-exchange` on `POST /oauth/token`, with
|
|
250
257
|
`subject_token_type`
|
|
251
|
-
`urn:collective-intelligence:params:oauth:token-type:session_token
|
|
252
|
-
|
|
258
|
+
`urn:collective-intelligence:params:oauth:token-type:session_token` and
|
|
259
|
+
`organization_id`; an external app sends no `scope`.
|
|
253
260
|
|
|
254
261
|
## Reuse Nest operations and local AI tools
|
|
255
262
|
|
|
@@ -503,7 +510,7 @@ succeeded before the new turn started count. A turn is
|
|
|
503
510
|
retried message replay the same turn instead of adding one. Use each key for
|
|
504
511
|
one message only; reusing it for a different message or conversation returns
|
|
505
512
|
`conflict`.
|
|
506
|
-
-
|
|
513
|
+
- `core.platform.conversations` in the caller's grants gates conversations.
|
|
507
514
|
- The Agent's current audience gates every turn and every `history` read. When
|
|
508
515
|
an administrator removes the caller from the audience, the same caller gets
|
|
509
516
|
`not_found` for its own conversations too.
|
|
@@ -511,14 +518,14 @@ succeeded before the new turn started count. A turn is
|
|
|
511
518
|
visitor's `auditSubject` (no `mappedUserId`). Only a declared Agent with
|
|
512
519
|
`audience: { anonymous: true }` that lists this application admits it. The
|
|
513
520
|
visitor's turns run with the Agent's own bindings under an anonymous visitor
|
|
514
|
-
subject, never with the application's
|
|
521
|
+
subject, never with the application's grants. Visitors are separate owners:
|
|
515
522
|
one visitor never reads another visitor's conversation.
|
|
516
523
|
|
|
517
524
|
## Messages
|
|
518
525
|
|
|
519
526
|
`messages.send` sends one message through a messaging connection of the
|
|
520
527
|
Organization, for example a Telegram bot or a WhatsApp Business Account. The
|
|
521
|
-
|
|
528
|
+
caller needs `core.platform.messaging` in its grants, and an administrator must grant
|
|
522
529
|
the connection to the application on its administration page.
|
|
523
530
|
|
|
524
531
|
```ts
|
|
@@ -562,46 +569,70 @@ const sent = await ci.messages.send({
|
|
|
562
569
|
reached its rate limit; it is retryable, and the client repeats it with the
|
|
563
570
|
same key.
|
|
564
571
|
|
|
565
|
-
##
|
|
572
|
+
## Members, guests, grants and Groups (`ci.access`)
|
|
566
573
|
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
574
|
+
`ci.access` manages the access of one Organization from your server. Call it
|
|
575
|
+
with the app's server credentials (`mode: "service"`), which act with the
|
|
576
|
+
grants an administrator gave the app's server, or with a service principal's
|
|
577
|
+
API key as the delegated token. CI authorizes each call with the caller's
|
|
578
|
+
Tuples: members and invitations need `admin.users`, guests `admin.guests`,
|
|
579
|
+
grants `admin.grants`, Groups `admin.groups`, and the read-only model
|
|
580
|
+
`admin.profiles`. A refused call rejects with `ServerAccessError` (`status`
|
|
581
|
+
and CI's error `body`). Calls are not retried.
|
|
570
582
|
|
|
571
583
|
```ts
|
|
572
|
-
const created = await ci.
|
|
573
|
-
email: "
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
584
|
+
const created = await ci.access.members.create({
|
|
585
|
+
email: "ada@example.test",
|
|
586
|
+
grants: [{ profile: "clinic.profiles.patient" }],
|
|
587
|
+
kind: "guest",
|
|
588
|
+
mode: "direct",
|
|
589
|
+
organizationId
|
|
590
|
+
})
|
|
591
|
+
|
|
592
|
+
const result = await ci.access.grants.sync({
|
|
593
|
+
grants: [
|
|
594
|
+
{
|
|
595
|
+
fqn: "clinic.patients.ada",
|
|
596
|
+
grantee: { user: { email: "ada@example.test" } },
|
|
597
|
+
profile: "clinic.profiles.patient"
|
|
598
|
+
}
|
|
599
|
+
],
|
|
600
|
+
namespace: "clinic.patients",
|
|
601
|
+
organizationId
|
|
578
602
|
})
|
|
579
|
-
//
|
|
580
|
-
// kind is "member" or "external_app_user".
|
|
603
|
+
// result = { created, updated, deleted, unchanged }: Access Grant FQNs.
|
|
581
604
|
```
|
|
582
605
|
|
|
583
|
-
- `
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
`
|
|
604
|
-
|
|
606
|
+
- `members`: `create` (directly or by invitation, with at least one grant;
|
|
607
|
+
Grant Authority decides each grant), `get`, `list` (`after`, `email`,
|
|
608
|
+
`limit`), `findByEmail`, `suspend`, `resume` and `remove`. An app server
|
|
609
|
+
creates, reads and changes only its own guests.
|
|
610
|
+
- `invitations`: `list` (`status`, `page`, `limit`) and `revoke`. Only a
|
|
611
|
+
service principal invites, so an app server is refused.
|
|
612
|
+
- `grants`: `create`, `get`, `update` and `delete` by `grantId` or `fqn`,
|
|
613
|
+
`list` by `userId`, `groupId` or `namespace`, and `sync` of a namespace.
|
|
614
|
+
A grant names its grantee as `{ user: { email } }`,
|
|
615
|
+
`{ group: { fqn }, coverage }`, `{ servicePrincipal: "<fqn>" }`, or an
|
|
616
|
+
app's `{ applicationServer: "<app fqn>" }` (a `server` profile) or
|
|
617
|
+
`{ applicationVisitors: "<app fqn>" }` (an `anonymous` profile). Every
|
|
618
|
+
grant has an Access Grant FQN; a Group without an FQN gets grants only in
|
|
619
|
+
the Dashboard.
|
|
620
|
+
- `groups`: `create`, `get`, `list` (`page`, `limit`), `update`, `delete`,
|
|
621
|
+
`addMember` and `removeMember` by `userId`. A member change of a Group
|
|
622
|
+
that a holders-only grant reaches also needs Grant Authority over that
|
|
623
|
+
grant. An app server reads Groups but writes none.
|
|
624
|
+
- `profiles.list`, `profiles.get`, `catalog.list`, `axes.list`,
|
|
625
|
+
`maxPrivileges.list`, `maxPrivileges.get`, `knowledgePolicies.list` and
|
|
626
|
+
`knowledgePolicies.forSchema({ organizationId, schemaFqn })` read the
|
|
627
|
+
declared model; the core and packages stay its source of truth.
|
|
628
|
+
`forSchema` answers the policies that decide the reads and the writes of
|
|
629
|
+
the schema, as CI fills its Policy Slots.
|
|
630
|
+
- A paged list answers `{ items, next }`: pass `next` back as `after`
|
|
631
|
+
(members) or `page` (Groups, invitations) to read the page after it.
|
|
632
|
+
- `snapshot({ organizationId, userId })` reads a user's Access Snapshot;
|
|
633
|
+
`explain` tells why a principal may use a capability or act on a record.
|
|
634
|
+
- There is no `ci.users` or `ci.roles`: app users became guests, and roles
|
|
635
|
+
became Access Grants of profiles.
|
|
605
636
|
|
|
606
637
|
## Durable files
|
|
607
638
|
|
|
@@ -634,7 +665,7 @@ await ci.workflows.invoke({
|
|
|
634
665
|
public URL, and another Organization cannot read it.
|
|
635
666
|
- `attachments.upload` is different: its file belongs to one run and expires
|
|
636
667
|
after 24 hours.
|
|
637
|
-
- It needs
|
|
668
|
+
- It needs `core.platform.attachments` in the app server's grants. Only service credentials may call it: a
|
|
638
669
|
delegated user token or an anonymous visitor gets `operation_not_allowed`.
|
|
639
670
|
|
|
640
671
|
### Entity File fields
|
|
@@ -687,10 +718,55 @@ if (slot.ok) {
|
|
|
687
718
|
values; a portable resource form has no File field, so
|
|
688
719
|
`projectResourceSchema` refuses them.
|
|
689
720
|
|
|
690
|
-
##
|
|
721
|
+
## Records
|
|
722
|
+
|
|
723
|
+
`resources.records` reads, searches, creates, updates and deletes the
|
|
724
|
+
records of an entity schema through CI's resources API.
|
|
725
|
+
|
|
726
|
+
### Record reads
|
|
727
|
+
|
|
728
|
+
```ts
|
|
729
|
+
const read = await ci.resources.records.get({
|
|
730
|
+
id: "lead-1",
|
|
731
|
+
include: ["company"],
|
|
732
|
+
organizationId,
|
|
733
|
+
schemaId: "acme.crm.lead"
|
|
734
|
+
})
|
|
735
|
+
const page = await ci.resources.records.search({
|
|
736
|
+
filter: { field: "status", operator: "eq", value: "open" },
|
|
737
|
+
organizationId,
|
|
738
|
+
pagination: { mode: "page", page: 1, pageSize: 20 },
|
|
739
|
+
schemaId: "acme.crm.lead",
|
|
740
|
+
sort: [{ direction: "desc", field: "createdAt" }]
|
|
741
|
+
})
|
|
742
|
+
```
|
|
691
743
|
|
|
692
|
-
`
|
|
693
|
-
|
|
744
|
+
- `get` sends `GET /application/v1/resources/:schemaId/records/:id`.
|
|
745
|
+
`include` names Include Paths, such as `["company", "contacts.company"]`.
|
|
746
|
+
The result is the record `{ id, revision, value }`; with `include`, it
|
|
747
|
+
also has `included`, and `truncated` names the keys whose records CI cut
|
|
748
|
+
to the first 100.
|
|
749
|
+
- `search` sends `POST /application/v1/resources/:schemaId/search` with
|
|
750
|
+
only the keys that the request gives: `filter`, `include`, `pagination`,
|
|
751
|
+
`sort` and `textSearch`. The query is the `EntityListQuery` of
|
|
752
|
+
`./resources`: `pagination` is `{ mode: "page", page, pageSize }`, with
|
|
753
|
+
`page >= 1` and `pageSize` from 1 to 100. The result is the page
|
|
754
|
+
`{ items, page, pageSize, pagination: "page", totalItems, totalPages }`
|
|
755
|
+
(`ServerRecordPage`).
|
|
756
|
+
- A read uses the credentials, the `timeoutMs`, the `signal` and the retry
|
|
757
|
+
policy of a write. A read sends no idempotency key. Each attempt sends
|
|
758
|
+
the same correlation id. A refusal resolves `{ ok: false, error }`; an
|
|
759
|
+
answer of CI that is not a record or a page rejects with
|
|
760
|
+
`CiTransportError`.
|
|
761
|
+
- A read asks no schema snapshot, invalidates no cache tag and adds no cache
|
|
762
|
+
tag: the SDK does not cache it. To cache a shared read in Next.js, call
|
|
763
|
+
[`cacheCiRead`](#nextjs-cache-primitives) with the service-mode client in
|
|
764
|
+
the app's `"use cache"` scope.
|
|
765
|
+
- `knowledge.getEntity` and `knowledge.searchEntities` do not reach CI:
|
|
766
|
+
they reject with `TypeError` and point to `/application/v1/resources`.
|
|
767
|
+
Use `resources.records.get` and `resources.records.search`.
|
|
768
|
+
|
|
769
|
+
### Record writes
|
|
694
770
|
|
|
695
771
|
```ts
|
|
696
772
|
const created = await ci.resources.records.create({
|
|
@@ -740,9 +816,8 @@ A schema declares its accounts field to name the users that act for each of its
|
|
|
740
816
|
records (see the [Knowledge User fields](../../../docs/reference/knowledge-user-fields.md)
|
|
741
817
|
reference). CI stores no other link between a user and a record, and offers no
|
|
742
818
|
operation that lists or changes one: write the accounts field as an
|
|
743
|
-
administrator
|
|
744
|
-
|
|
745
|
-
and the caller as `subject` path `["user", "id"]`.
|
|
819
|
+
administrator or with the workflow account step. A Knowledge Data Condition
|
|
820
|
+
reads it with `isMe("accounts")` or `includesMe("accounts")`.
|
|
746
821
|
|
|
747
822
|
- A delegated user's `/application/v1/resources` and `knowledge_*` calls, and
|
|
748
823
|
the Agents, Skills and workflows the user runs, decide under the user's
|
|
@@ -986,9 +1061,16 @@ that reads Effect `Config`:
|
|
|
986
1061
|
request)` keeps the CI error envelope as a value; `execute` fails with
|
|
987
1062
|
`CiError`. A transport failure fails with `CiTransportError`.
|
|
988
1063
|
`sendMessage` and `createUpload` keep the refusal of CI as a value.
|
|
989
|
-
`records.
|
|
1064
|
+
`records.get`, `records.search` ([Record reads](#record-reads)) and
|
|
1065
|
+
`records.create`, `records.update`, `records.delete`
|
|
990
1066
|
([Record writes](#record-writes)) fail with `CiError`; `recordsResult`
|
|
991
|
-
has the same
|
|
1067
|
+
has the same methods and keeps the refusal of CI as a value.
|
|
1068
|
+
- `layerDelegatedServerClient(config)`: one app-wide `ServerClient` that
|
|
1069
|
+
calls CI as the member of each request. `config` is a client config
|
|
1070
|
+
without `authentication`. Each attempt sends the `DelegatedAccessToken` of
|
|
1071
|
+
the calling fiber as `Bearer`; provide it per request. A call on a fiber
|
|
1072
|
+
without one dies with `TypeError` and sends no request. The method types
|
|
1073
|
+
do not change. Use it in place of one client for each member token.
|
|
992
1074
|
- Without a `sleep` option, the retry backoff of `ServerClient` is
|
|
993
1075
|
`Effect.sleep` on the Clock: `TestClock` drives it, and an interruption
|
|
994
1076
|
stops it. With `sleep`, the client waits on that function.
|
|
@@ -1026,6 +1108,28 @@ const program = ServerClient.use((client) =>
|
|
|
1026
1108
|
)
|
|
1027
1109
|
```
|
|
1028
1110
|
|
|
1111
|
+
One client for all members, with the token of each request on its fiber:
|
|
1112
|
+
|
|
1113
|
+
```ts
|
|
1114
|
+
import * as Effect from "effect/Effect"
|
|
1115
|
+
import * as Option from "effect/Option"
|
|
1116
|
+
import {
|
|
1117
|
+
DelegatedAccessToken,
|
|
1118
|
+
layerDelegatedServerClient,
|
|
1119
|
+
ServerClient
|
|
1120
|
+
} from "@collective-intelligence/external-apps-server-sdk/effect"
|
|
1121
|
+
|
|
1122
|
+
// Build the layer once, in the app runtime.
|
|
1123
|
+
const CiLive = layerDelegatedServerClient({
|
|
1124
|
+
tenantUrl: "https://tenant.example"
|
|
1125
|
+
})
|
|
1126
|
+
|
|
1127
|
+
const readLead = (memberToken: string, id: string) =>
|
|
1128
|
+
ServerClient.use((client) =>
|
|
1129
|
+
client.records.get({ id, organizationId, schemaId: "acme.crm.lead" })
|
|
1130
|
+
).pipe(Effect.provideService(DelegatedAccessToken, Option.some(memberToken)))
|
|
1131
|
+
```
|
|
1132
|
+
|
|
1029
1133
|
`DateTimeString` and `UuidV7` provide reusable wire schemas;
|
|
1030
1134
|
`jsonSchema` projects an Effect schema into the JSON Schema document accepted
|
|
1031
1135
|
by gateway resource and operation definitions. The projection rejects unknown
|
|
@@ -1496,13 +1600,16 @@ const handle = createResourceHttpHandler({
|
|
|
1496
1600
|
```
|
|
1497
1601
|
|
|
1498
1602
|
`auth` is the existing `createFederatedAuth(...)` instance. Its server-only
|
|
1499
|
-
`getEntityContext` resolves
|
|
1500
|
-
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
`
|
|
1505
|
-
|
|
1603
|
+
`getEntityContext` resolves the CI application, user, organization and the
|
|
1604
|
+
app's slice of the user's capabilities (`capabilities`) for the session's
|
|
1605
|
+
Access token; CI is asked for that identity once per Access
|
|
1606
|
+
token, and again only after an observed CI answer shows a change. CI never sends Group IDs. The browser session JSON at
|
|
1607
|
+
`<basePath>/session` carries `expiresAt` and an `identity` with `userId`,
|
|
1608
|
+
`organizationId`, `appId`, `kind` (`member`, `guest`, or `null` for a tenant
|
|
1609
|
+
user without a membership), `access` (the app's slice of the user's access),
|
|
1610
|
+
`email` and `name`; it never carries the Access token. A user that does not
|
|
1611
|
+
enter the app (no capability at or below the app gate) has no session and no
|
|
1612
|
+
entity access. Local Better Auth sessions do
|
|
1506
1613
|
not establish CI entity authority. Browser framework adapters require this
|
|
1507
1614
|
verified context instead of boolean authorization. Machine gateway calls retain
|
|
1508
1615
|
their separate caller policy.
|
|
@@ -1578,7 +1685,7 @@ pagination, predicates, grouping, aggregates or managed extraction.
|
|
|
1578
1685
|
Import `createFederatedAuth` from
|
|
1579
1686
|
`@collective-intelligence/external-apps-server-sdk/auth/federated`. Supply the
|
|
1580
1687
|
browser-visible HTTPS application origin, CI issuer, OAuth client, organization,
|
|
1581
|
-
audience,
|
|
1688
|
+
audience, and an application-owned atomic session store. The facade owns
|
|
1582
1689
|
PKCE login, callback, session inspection and logout under `/api/auth` by default.
|
|
1583
1690
|
|
|
1584
1691
|
`applicationOrigin` accepts one HTTPS origin or a list. Use a list when one
|
|
@@ -1591,7 +1698,6 @@ const auth = createFederatedAuth({
|
|
|
1591
1698
|
clientId,
|
|
1592
1699
|
issuer,
|
|
1593
1700
|
organizationId,
|
|
1594
|
-
scopes: ["knowledge:read"],
|
|
1595
1701
|
session: { kind: "sealed_cookie", secrets }
|
|
1596
1702
|
})
|
|
1597
1703
|
```
|
|
@@ -1618,9 +1724,12 @@ authorization code to its `redirect_uri`, so an unregistered callback fails at
|
|
|
1618
1724
|
authorization.
|
|
1619
1725
|
|
|
1620
1726
|
The store persists only hashed opaque-cookie state, token grants and revisions;
|
|
1621
|
-
the browser receives a `Secure`, `HttpOnly`, `SameSite=Lax` host cookie.
|
|
1622
|
-
session lookup
|
|
1623
|
-
|
|
1727
|
+
the browser receives a `Secure`, `HttpOnly`, `SameSite=Lax` host cookie. A
|
|
1728
|
+
session lookup reads the CI identity of its Access token once per token and
|
|
1729
|
+
again after a `401` or a changed `x-access-version` that
|
|
1730
|
+
`auth.observeCiResponse` sees. A revocation therefore ends application
|
|
1731
|
+
authorization at the next token renewal (at most 300 seconds) or at once when a
|
|
1732
|
+
forwarded CI answer reports it. A confidential
|
|
1624
1733
|
OAuth client may supply `clientSecret`; a public PKCE client omits it. The
|
|
1625
1734
|
client type decides how long the User session lasts; see
|
|
1626
1735
|
[Session lifetime and renewal](#session-lifetime-and-renewal).
|
|
@@ -1658,8 +1767,9 @@ each `sessionTtlSeconds` value in the range and gives no warning.
|
|
|
1658
1767
|
`getSession`, `getAccessToken`, `getEntityContext` and
|
|
1659
1768
|
`GET <basePath>/session` are the session lookups. With renewal, each lookup
|
|
1660
1769
|
first gets a new Access token when the current one is expired or expires in 30
|
|
1661
|
-
seconds or less. Then it
|
|
1662
|
-
lookup never returns an expired Access
|
|
1770
|
+
seconds or less. Then it reads the identity of that token at
|
|
1771
|
+
`/oauth/identity`, once per token. A lookup never returns an expired Access
|
|
1772
|
+
token. Lookups at the same time share
|
|
1663
1773
|
one renewal request.
|
|
1664
1774
|
|
|
1665
1775
|
The SDK writes the cookie or the store record one time, at sign-in. A renewal
|
|
@@ -1698,10 +1808,8 @@ A renewal applies the same admission rule as `/oauth/identity`:
|
|
|
1698
1808
|
|
|
1699
1809
|
- the external Application is enabled;
|
|
1700
1810
|
- the CI session is live;
|
|
1701
|
-
- the user is not banned
|
|
1702
|
-
|
|
1703
|
-
`anonymous` (Direct Role Assignments replace the roles that Groups give);
|
|
1704
|
-
- the scopes of the sign-in are still allowed.
|
|
1811
|
+
- the user is not banned and enters the app: its Tuples hold the app gate
|
|
1812
|
+
or a capability below it.
|
|
1705
1813
|
|
|
1706
1814
|
A refusal ends nothing. When the condition is corrected, the same Renewal
|
|
1707
1815
|
credential renews again. A Federated authorization ends for good only by one
|
|
@@ -1779,10 +1887,10 @@ import {
|
|
|
1779
1887
|
const tokens = createAccessTokenVerifier(readApplicationEnrollment(process.env))
|
|
1780
1888
|
|
|
1781
1889
|
const caller = await tokens.verify(bearerToken)
|
|
1782
|
-
// userId, organizationId, applicationId, clientId,
|
|
1890
|
+
// userId, organizationId, applicationId, clientId, sessionId, expiresAt
|
|
1783
1891
|
|
|
1784
1892
|
const identity = await tokens.identity(bearerToken, { signal: request.signal })
|
|
1785
|
-
// the same fields, and user { id, email, name }, kind,
|
|
1893
|
+
// the same fields, and user { id, email, name }, kind, access
|
|
1786
1894
|
```
|
|
1787
1895
|
|
|
1788
1896
|
- `verify` is offline against the issuer key set: ES256 signature, issuer,
|
|
@@ -1790,10 +1898,10 @@ const identity = await tokens.identity(bearerToken, { signal: request.signal })
|
|
|
1790
1898
|
It does not see a revocation before the token expires.
|
|
1791
1899
|
- `identity` runs `verify`, then reads CI's current identity for the token and
|
|
1792
1900
|
checks that it describes the same grant. Use it when the API needs the
|
|
1793
|
-
|
|
1794
|
-
the token or
|
|
1901
|
+
app's slice of the user's access (`access.capabilities`), or must stop at
|
|
1902
|
+
once when CI revokes the token or the user leaves the app. It
|
|
1795
1903
|
is one CI request for each call, with a 10-second limit; cache the result
|
|
1796
|
-
for as long as
|
|
1904
|
+
for as long as an access change may take to reach your API. Pass the `signal`
|
|
1797
1905
|
of the request you serve: when it aborts, the CI request ends and the call
|
|
1798
1906
|
rejects with the abort reason.
|
|
1799
1907
|
|
|
@@ -1811,7 +1919,8 @@ const resource = defineCiEntityResource({
|
|
|
1811
1919
|
definition: leadDefinition,
|
|
1812
1920
|
tenantUrl: "https://ci.example.com",
|
|
1813
1921
|
organizationId,
|
|
1814
|
-
schemaFqn
|
|
1922
|
+
schemaFqn,
|
|
1923
|
+
observeCiResponse: auth.observeCiResponse
|
|
1815
1924
|
})
|
|
1816
1925
|
```
|
|
1817
1926
|
|
|
@@ -2031,7 +2140,7 @@ CI-backed resources created by `defineCiEntityResource` accept the common client
|
|
|
2031
2140
|
mounts `POST /records/:parentId/relation-members/search` below the resource base
|
|
2032
2141
|
path and forwards `{ field, ...query }` to the bound CI schema route. Existing
|
|
2033
2142
|
verified tenant, organization, resource and user-grant checks still apply;
|
|
2034
|
-
`authorizeWithUserAuth` classifies this operation under `
|
|
2143
|
+
`authorizeWithUserAuth` classifies this operation under its `read` Requirement.
|
|
2035
2144
|
|
|
2036
2145
|
The page envelope and exact totals remain unchanged. Member records are JSON
|
|
2037
2146
|
objects validated independently of the parent schema, as are member query field
|