@collective-intelligence/external-apps-server-sdk 0.3.9 → 0.4.1

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/README.md CHANGED
@@ -1799,7 +1799,7 @@ again after a `401` or a changed `x-access-version` that
1799
1799
  authorization at the next token renewal (at most 300 seconds) or at once when a
1800
1800
  forwarded CI answer reports it. A confidential
1801
1801
  OAuth client may supply `clientSecret`; a public PKCE client omits it. The
1802
- client type decides how long the User session lasts; see
1802
+ client type and the Session kind decide how long the User session lasts; see
1803
1803
  [Session lifetime and renewal](#session-lifetime-and-renewal).
1804
1804
 
1805
1805
  ### Sign-in failures at the callback
@@ -1839,24 +1839,31 @@ the User session ends when its Access token expires, 300 seconds after
1839
1839
  sign-in, whatever the value of `sessionTtlSeconds`. The Access token lifetime
1840
1840
  is always 300 seconds. There is no setting for it.
1841
1841
 
1842
- Renewal needs these three conditions:
1842
+ Renewal needs one of these two setups:
1843
1843
 
1844
- - The external Application is confidential at CI.
1845
- - `createFederatedAuth` gets the `clientSecret` of that Application.
1846
- - The user signed in after the upgrade to an SDK version that renews. An
1847
- earlier cookie or store record holds no Renewal credential. That User
1848
- session ends at its Access token expiry.
1844
+ - A confidential external Application, and `createFederatedAuth` gets its
1845
+ `clientSecret`.
1846
+ - A public external Application with the `store` Session kind:
1847
+ `session: { kind: "store", store }`, or the top-level `store` option with no
1848
+ `session`.
1849
1849
 
1850
- When the three conditions are true, CI returns a Renewal credential at
1851
- sign-in. On the wire it is the OAuth `refresh_token`. The SDK keeps it in the
1852
- session record and uses it to get a new Access token with no browser redirect.
1853
- The application code does not change.
1850
+ The user must also sign in after the upgrade to an SDK version that renews.
1851
+ An earlier cookie or store record holds no Renewal credential. That User
1852
+ session ends at its Access token expiry.
1854
1853
 
1855
- A public client has no client secret, so it gets no Renewal credential. Its
1856
- User session lasts 300 seconds. To continue, the application sends the browser
1857
- to `<basePath>/login` again, as before. A `fetch` call or a form post cannot
1858
- follow that redirect. For a public client, `createFederatedAuth` still accepts
1859
- each `sessionTtlSeconds` value in the range and gives no warning.
1854
+ CI returns a Renewal credential at every sign-in. On the wire it is the OAuth
1855
+ `refresh_token`. In one of the two setups, the SDK keeps it in the session
1856
+ record and uses it to get a new Access token with no browser redirect. The
1857
+ application code does not change.
1858
+
1859
+ A public client with the `sealed_cookie` Session kind keeps no Renewal
1860
+ credential: each public renewal replaces the credential, and a session lookup
1861
+ cannot rewrite the sealed cookie. Its User session lasts 300 seconds. To
1862
+ continue, the application sends the browser to `<basePath>/login` again, as
1863
+ before. A `fetch` call or a form post cannot follow that redirect. For such a
1864
+ client, `createFederatedAuth` still accepts each `sessionTtlSeconds` value in
1865
+ the range and gives no warning. To renew, use the `store` Session kind, or a
1866
+ confidential Application with `clientSecret`.
1860
1867
 
1861
1868
  `getSession`, `getAccessToken`, `getEntityContext` and
1862
1869
  `GET <basePath>/session` are the session lookups. With renewal, each lookup
@@ -1866,11 +1873,21 @@ seconds or less. Then it reads the identity of that token at
1866
1873
  token. Lookups at the same time share
1867
1874
  one renewal request.
1868
1875
 
1869
- The SDK writes the cookie or the store record one time, at sign-in. A renewal
1870
- writes no cookie and no store record. A renewed Access token stays only in
1871
- process memory. Each `createFederatedAuth` instance keeps at most 5000 of
1872
- them, separate from each other instance. A restart loses them, and the next
1873
- lookup renews again.
1876
+ For a confidential client, the SDK writes the cookie or the store record one
1877
+ time, at sign-in. A renewal writes no cookie and no store record. A renewed
1878
+ Access token stays only in process memory. Each `createFederatedAuth` instance
1879
+ keeps at most 5000 of them, separate from each other instance. A restart loses
1880
+ them, and the next lookup renews again.
1881
+
1882
+ For a public client, each renewal is a Rotation: CI returns a new Renewal
1883
+ credential and replaces the one presented. The SDK writes the new credential
1884
+ and Access token to the store record with `store.replace`, on the revision
1885
+ that the lookup read. Instances that share one store can renew the same record
1886
+ at the same time; each lookup returns a session. CI gives the replaced
1887
+ credential the same new credential for 30 seconds after the Rotation, so a
1888
+ renewal whose answer was lost succeeds again inside that window. After the
1889
+ window, the replaced credential ends the Federated authorization (Reuse
1890
+ detection), and the lookup returns `null`.
1874
1891
 
1875
1892
  A Federated authorization is the record that CI keeps of one sign-in to one
1876
1893
  external Application. It lasts at most 604800 seconds from sign-in, and never
@@ -1908,12 +1925,21 @@ A renewal applies the same admission rule as `/oauth/identity`:
1908
1925
  A refusal ends nothing. When the condition is corrected, the same Renewal
1909
1926
  credential renews again. A Federated authorization ends for good only by one
1910
1927
  of these events: logout, a new sign-in in the same User session, its limit of
1911
- 604800 seconds, or the end of the CI session.
1912
-
1913
- `POST <basePath>/logout` presents the Renewal credential to CI, and CI ends
1914
- the Federated authorization. If CI does not answer, the route answers `503`
1915
- and still clears the User session. That Federated authorization then ends at
1916
- its limit or with its CI session.
1928
+ 604800 seconds, the end of the CI session, or, for a public client, Reuse
1929
+ detection.
1930
+
1931
+ `POST <basePath>/logout` ends the grant at CI. A User session with a Renewal
1932
+ credential presents it; a public client also sends its Access token. A User
1933
+ session without one sends its Access token as bearer, with `client_id`. For a
1934
+ confidential client CI ends the Federated authorization of the credential. For
1935
+ a public client CI ends every Federated authorization of the Application in
1936
+ the CI session of the user, also those of other User sessions. If CI does
1937
+ not answer, the route answers `503` and still clears the User session. That
1938
+ Federated authorization then ends at its limit or with its CI session.
1939
+
1940
+ A new sign-in in the same User session ends only the earlier Federated
1941
+ authorization; the SDK sends `end=authorization` for it. The other User
1942
+ sessions of the CI session stay.
1917
1943
 
1918
1944
  An application that does not use this SDK finds the CI token and logout
1919
1945
  contract in