Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/fork-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,8 @@ jobs:
bun run e2e:apps-published -- --testNamePattern 'self-host gate'
- name: Tool error contract scenarios
run: bun run e2e:self-host --test-name 'Every error tools/call and tools/run declare|Every error a write reports after its app code received the call'
- name: Reused app account scenario
run: bun run e2e:self-host --test-name '^a reused hosted app account (stops serving|refuses a call)' --workers 1
- name: Operator feedback scenarios
run: bun run e2e:self-host --test-name 'self-host feedback webhook|self-host with DO_NOT_TRACK|self-host analytics pseudonymize|Hosted feedback enforces'
# Run the large cold catalog alone, not beside the functional scenarios' servers.
Expand Down
25 changes: 21 additions & 4 deletions apps/docs/content/concepts/providers-and-accounts.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,15 +116,32 @@ with your links.

People who can edit an app link its app accounts for everyone, in the **App
accounts** section of the app's **Accounts** tab. Linking needs edit access to
the app, and the account must be your own: accounts are never shared, so this is
how one account serves everyone. It stops serving if its owner leaves the
organization. Callers use the account through the app without
the app, and the account must be your own: accounts are never shared, so this
is how one account serves everyone. An organization owner or admin may also
reuse an account already linked for everyone to an app they can read and edit
with the same calling credential. A credential limited to selected apps cannot
reuse accounts from apps outside that selection. Reuse is not allowed
into an app a member created, unless that member owns the account, nor into one
created by someone who has since left the organization or an app without a
creator. The same rule applies when the link is used. If a creator who does not
own the account is demoted or leaves, or the app loses its creator, the reused
link stops serving with `AppLinkCreatorNotAuthorized` (409). Deleting a user
also removes reused links from the apps they created.
If that creator becomes an admin or owner again, the stored link can serve
again. An admin can relink an eligible account, or the account's owner can link
it directly if they can edit the app. A link made by the account owner does not
depend on the creator's role. The account stays its owner's, and its owner may
unlink it from any app. It stops serving if its owner leaves the organization.
Callers use the account through the app without
access to the account itself, and they cannot choose or replace it; everyone
else sees the section read-only, without the account's details from the
provider. Linking another account to a plain slot replaces the one before; a
`.many()` slot uses every linked account. Unlinking stops the app using the
account, which stays saved. An account linked to an app for everyone cannot be
deleted until it is unlinked. The same account may also be linked for yourself.
deleted until it is unlinked. Its owner can call `appAccounts.appUnlinkOwned` with
the account and app ids to remove all its app links there, even when the app is
private and they cannot read its requirement names. This returns only those ids,
not the app's contents. The same account may also be linked for yourself.

When an app account needs reconnecting, the people who can edit the app are
told, and a call that needs it fails saying that one of them must reconnect it.
Expand Down
12 changes: 9 additions & 3 deletions apps/docs/content/connect-an-account.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,11 @@ linked to a single-account requirement and every account you linked to a
`.many()` requirement; for each of the app's own requirements, the accounts
linked for everyone. A single-account requirement with no account fails with
`AccountRequired`, which says whether you need to link one or someone who can
edit the app does. A tool input that passes `$accounts` fails with
edit the app does. A reused app link whose creator is missing or no longer an
organization admin or owner fails with `AppLinkCreatorNotAuthorized` (409), unless the
creator owns the account or the account's owner made the link. Ask an admin to
relink an eligible account, or ask the account's owner to link it directly.
A tool input that passes `$accounts` fails with
`AccountChoiceUnsupported`.

To use a different account, link it on the app's **Accounts** tab. To use two
Expand All @@ -193,7 +197,9 @@ from an app that uses the account: open its menu on the app's **Accounts** tab a
linked to it keeps working.

Removing an account removes your links to it. An account linked to an app for
everyone cannot be removed until someone who can edit the app unlinks it
(`AccountLinkedToApp`). An app left with no account
everyone cannot be removed until it is unlinked (`AccountLinkedToApp`). As its
owner, call `appAccounts.appUnlinkOwned` with the account and each app id named by
that error. This removes all its app links there without needing access to the
app or its requirement names. An app left with no account
for a requirement exposes no tools until you link or connect another. Executor
does not substitute a different account.
4 changes: 2 additions & 2 deletions apps/hosted/server/src/contracts/accounts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ export const AccountLinkedToApp = UserFacingError.define({
description:
"An app uses this account for everyone who uses the app, so it can't be deleted while it is linked.",
recovery: {
action: "Ask someone who can edit each app to unlink the account, then delete it.",
action: "Unlink your account from each named app, then delete it.",
instructions:
"Read the app accounts of each named app with appAccounts.appList and unlink this account with appAccounts.appUnlink, or ask someone who can edit the app to. Link a replacement first if the app still needs one. Then delete the account.",
"Call appAccounts.appUnlinkOwned with this account and each named app id to remove all of your account's app links there. You do not need access to the app or its requirement names. Ask an editor to link a replacement first if the app still needs one. Then delete the account.",
},
});
/** Parsed AccountLinkedToApp failure. */
Expand Down
18 changes: 15 additions & 3 deletions apps/hosted/server/src/contracts/app-accounts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ const scopeEndpoints = <const S extends AccountScope>(scope: S) => {
.annotate(
OpenApi.Description,
forEveryone
? "Read one of this app's own requirements: the accounts linked to it, then the other accounts of its provider you can use and could link, each marked linked or not. Needs edit access to the app."
? "Read one of this app's own requirements: the accounts linked to it, then the other accounts of its provider you could link, each marked linked or not: your own and, for an organization owner or admin, accounts already linked for everyone to an app they can edit, unless a member other than the account's owner, or someone who has since left the organization, created this app. Needs edit access to the app."
: "Read one of this app's user requirements: the accounts you linked to it, then the other accounts of its provider you can use and could link, each marked linked or not. Choose from these accounts before linking.",
),
HttpApiEndpoint.put(`${scope}Link`, `${path}/:requirement/:account`, {
Expand All @@ -205,7 +205,7 @@ const scopeEndpoints = <const S extends AccountScope>(scope: S) => {
.annotate(
OpenApi.Description,
forEveryone
? "Link an account to one of this app's own requirements, so every caller and the app's background work use it through the app, without access to the account itself. Needs edit access to the app and use of the account. Linking an account to a plain requirement replaces the account linked to it before; for many() it adds one. Linking again changes nothing. The replaced account stays saved."
? "Link an account to one of this app's own requirements, so every caller and the app's background work use it through the app, without access to the account itself. Needs edit access to the app, and the account must be your own, or, for an organization owner or admin, already linked for everyone to an app they can edit and this app not created by a member other than the account's owner or by someone who has since left the organization; it stays its owner's. Linking an account to a plain requirement replaces the account linked to it before; for many() it adds one. Linking again changes nothing. The replaced account stays saved."
: "Link one of your accounts to one of this app's user requirements. Needs use of the app and of the account. Linking an account to a plain requirement replaces the account you linked to it before; for many() it adds one. Linking again changes nothing. The replaced account stays saved.",
),
HttpApiEndpoint.delete(`${scope}Unlink`, `${path}/:requirement/:account`, {
Expand All @@ -217,7 +217,7 @@ const scopeEndpoints = <const S extends AccountScope>(scope: S) => {
.annotate(
OpenApi.Description,
forEveryone
? "Stop this app using an account for one of its own requirements. Needs edit access to the app, not use of the account. Calls and background work that need the requirement fail until another account is linked, and the app's webhooks registered with the account are removed. The account stays saved."
? "Stop this app using an account for one of its own requirements. Needs edit access to the app, not use of the account, or ownership of the account. Calls and background work that need the requirement fail until another account is linked, and the app's webhooks registered with the account are removed. The account stays saved."
: "Stop using an account for one of this app's user requirements. The account and its other links stay unchanged.",
),
HttpApiEndpoint.post(`${scope}Connect`, `${path}/:requirement/connections`, {
Expand Down Expand Up @@ -251,6 +251,18 @@ export const HostedAppAccounts = HttpApiGroup.make("appAccounts")
.add(appGet)
.add(appLink)
.add(appUnlink)
.add(
HttpApiEndpoint.delete("appUnlinkOwned", `${prefix}/app/:account`, {
params: { ...app, account: AccountId },
success: Schema.Struct({ app: AppId, account: AccountId }),
error: [StorageError, OrganizationForbidden],
})
.annotate(RequiredAction, "manage")
.annotate(
OpenApi.Description,
"As the account's owner, stop one app using it for everyone across all requirements. Needs only the app id, not access to the app or its requirement names. Returns only the app and account ids. An app without one of your account's app links is forbidden, whether it exists or not. The account stays saved.",
),
)
.add(appConnect)
.add(userList)
.add(userGet)
Expand Down
3 changes: 3 additions & 0 deletions apps/hosted/server/src/contracts/security-audit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@ export const SecurityAuditAction = Schema.Literals([
"organization.delete",
"user.delete",
"credential.read",
"app_account.link",
"app_account.unlink",
"app_account.use_refused",
]);
export type SecurityAuditAction = typeof SecurityAuditAction.Type;

Expand Down
2 changes: 2 additions & 0 deletions apps/hosted/server/src/contracts/tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import {
AccountChoiceUnsupported,
AccountNotFound,
AccountRequired,
AppLinkCreatorNotAuthorized,
AccountSelectionInvalid,
AppEvaluationFailed,
AppProviderFailed,
Expand Down Expand Up @@ -67,6 +68,7 @@ const discoveryErrors = [
AppProviderFailed,
AccountNotFound,
AccountRequired,
AppLinkCreatorNotAuthorized,
AccountChoiceUnsupported,
AccountSelectionInvalid,
OAuthReconnectRequired,
Expand Down
8 changes: 6 additions & 2 deletions apps/hosted/server/src/implementation/access.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,9 @@ import {
import { refuse } from "./auth-telemetry.ts";
import {
appAccountReads,
appLinkedAccounts,
checkedAppLinkedAccounts,
callerAccounts,
refuseAppLinkCreators,
versionAccounts,
} from "./app-accounts.ts";
import {
Expand Down Expand Up @@ -405,7 +406,10 @@ const checkAppLinked = (app: AppId, linked: AppAccounts["app"]) =>
ids.map((id) => ({ requirement, id })),
);
if (used.length === 0) return;
const current = yield* appLinkedAccounts(yield* policyDatabase, [app]);
const current = (yield* checkedAppLinkedAccounts(yield* policyDatabase, app)).filter((link) =>
used.some(({ requirement, id }) => link.requirement === requirement && link.id === id),
);
yield* refuseAppLinkCreators(current);
for (const { requirement, id } of used)
if (!current.some((link) => link.requirement === requirement && link.id === id))
return yield* new OrganizationForbidden();
Expand Down
29 changes: 17 additions & 12 deletions apps/hosted/server/src/implementation/accounts.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { accountOAuthRedirectUri } from "./auth.ts";
import { audited } from "./security-audit.ts";
import { audited, withCommittedAudits } from "./security-audit.ts";
import { ScheduleWakeup } from "../contracts/schedules.ts";
import { CurrentPolicy } from "../contracts/authorization.ts";
import { permittedAppIds } from "@executor-js/authorization";
Expand Down Expand Up @@ -270,9 +270,10 @@ export const submitConnection = (
Effect.gen(function* () {
const executor = yield* Effect.flatten(HostedExecutor);
yield* checkConnection(yield* ownedConnection(executor, owner, input.connection));
return yield* executor.accountConnections
.submit({ ...input, owner })
.pipe(Effect.tap(() => Effect.flatten(ScheduleWakeup)));
return yield* executor.accountConnections.submit({ ...input, owner }).pipe(
withCommittedAudits,
Effect.tap(() => Effect.flatten(ScheduleWakeup)),
);
});
/**
* The member's client choice is checked against its audience here, then named to the SDK, which
Expand All @@ -289,11 +290,14 @@ export const startOAuth = (
yield* checkConnection(yield* ownedConnection(executor, owner, input.connection));
const client = yield* connectionClient(executor, owner, input);
const { client: _selected, ...rest } = input;
return yield* executor.accountConnections.startOAuth({
...rest,
owner,
...(client === undefined ? {} : { client }),
});
// A sign-in that needs no redirect completes here, linking the account as completion does.
return yield* executor.accountConnections
.startOAuth({
...rest,
owner,
...(client === undefined ? {} : { client }),
})
.pipe(withCommittedAudits);
});
/** Completion rechecks connection and target ownership before saving provider credentials. */
export const completeOAuth = (
Expand All @@ -303,9 +307,10 @@ export const completeOAuth = (
Effect.gen(function* () {
const executor = yield* Effect.flatten(HostedExecutor);
yield* checkConnection(yield* ownedConnection(executor, owner, input.connection));
return yield* executor.accountConnections
.completeOAuth({ ...input, owner })
.pipe(Effect.tap(() => Effect.flatten(ScheduleWakeup)));
return yield* executor.accountConnections.completeOAuth({ ...input, owner }).pipe(
withCommittedAudits,
Effect.tap(() => Effect.flatten(ScheduleWakeup)),
);
});

/** Account policy and persisted connection ownership protect management and OAuth return requests. */
Expand Down
Loading
Loading