Public Access
jaap-jan
d5b1a73182
Adding somebody to a team granted them nothing readable and removing them
rotated nothing. Both were honest — the interface said so in as many words — and
both left the actual work to a button somebody had to remember to press, on a
machine that happened to hold the key. Adding now wraps every team vault this
machine can open to the new member, and removing revokes their grants and moves
each of those vaults to a fresh key that goes to whoever is left.
The rotation is where the design had to be decided rather than written. A vault
key is per generation and an item carries the generation it was sealed under, so
advancing the vault and withdrawing the old grants would make everything already
stored unreadable to everybody, including whoever pressed the button. So earlier
grants are kept: a member holds one per generation, /me serves them as
PriorKeyWraps, and VaultKeyring holds a key per generation — the newest for
writing, the item's own for reading, chosen per item on every read path. Sharing
issues one grant per generation held, because a recipient handed only the current
key would open the vault to find most of it undecryptable; revocation takes every
generation, because leaving the history behind leaves them able to read
everything written before the rotation.
The bump itself is one server transaction. POST /vaults/{id}/rekey must name
exactly current + 1 and the vault's xmin token makes that binding, so two admins
rotating at once do not both walk away believing they succeeded — the second is
refused and told to read the vault again. The server contributes the moment and
no cryptography: it cannot generate the key, cannot tell that the one it is
handed differs from the old one, and checks that the caller held the old one the
only way it can, by requiring a live grant at the current generation.
What this does not do is re-encrypt what is already stored, and the product says
so rather than the reassuring version: everything written from the rotation
onwards is unreadable to the person who left, and nothing about the past changes.
That half is deferred and is safe to add incrementally precisely because a vault
at mixed generations stays readable. ADR 0010 records the alternatives — revoking
the old grants, chaining each key under its successor, re-sealing every item in
one request against a server that caps a push at 500 operations — and why each
was rejected.
Two things fell out of the change rather than being asked for. The grant listing
would have shown a member once per generation, so it now returns one row per
holder carrying the best key they hold, which is what makes a row below the
vault's generation mean "still owed the new key". And MarkUnreadable gives up the
write target as well as reporting: a client whose vault was rotated elsewhere
would otherwise have gone on sealing items under its superseded key — readable to
its author, unreadable to everybody else, with nothing to show for it.
244 lines
8.6 KiB
C#
244 lines
8.6 KiB
C#
using DodoSSH.Api.Authorization;
|
|
using DodoSSH.Api.Setup;
|
|
using DodoSSH.Contracts;
|
|
using DodoSSH.Domain.Authorization;
|
|
using FastEndpoints;
|
|
using Microsoft.AspNetCore.Http.HttpResults;
|
|
|
|
namespace DodoSSH.Api.Features.Teams;
|
|
|
|
/// <summary>Lists who can open a vault.</summary>
|
|
/// <remarks>
|
|
/// Read, not Share. Every member who can read a vault can already see the sharing graph — the server
|
|
/// stores it in plaintext and says so in docs/crypto.md §10 — so gating this on Share would hide from
|
|
/// the people it is about something the operator can read either way.
|
|
/// </remarks>
|
|
internal sealed class ListVaultGrantsEndpoint(
|
|
ICurrentUserContext currentUser,
|
|
IVaultAccessService vaultAccess,
|
|
VaultGrantService grants)
|
|
: EndpointWithoutRequest<Results<Ok<VaultGrantsResponse>, NotFound>>
|
|
{
|
|
/// <inheritdoc />
|
|
public override void Configure()
|
|
{
|
|
Get("/api/v1/vaults/{vaultId:guid}/grants");
|
|
|
|
Policies(Auth.EnrolledPolicy);
|
|
|
|
Description(b => b
|
|
.WithName("ListVaultGrants")
|
|
.WithSummary("Lists who holds a key to this vault.")
|
|
.WithTags("Vaults"));
|
|
}
|
|
|
|
/// <inheritdoc />
|
|
public override async Task<Results<Ok<VaultGrantsResponse>, NotFound>> ExecuteAsync(
|
|
CancellationToken ct)
|
|
{
|
|
var user = await currentUser.GetOrProvisionAsync(ct).ConfigureAwait(false);
|
|
var access = await vaultAccess
|
|
.ResolveAsync(user.Id, Route<Guid>("vaultId"), ct)
|
|
.ConfigureAwait(false);
|
|
|
|
if (!access.Granted || !access.Permissions.HasFlag(PermissionFlags.Read))
|
|
{
|
|
return TypedResults.NotFound();
|
|
}
|
|
|
|
return TypedResults.Ok(await grants.ListGrantsAsync(access.Vault!, ct).ConfigureAwait(false));
|
|
}
|
|
}
|
|
|
|
/// <summary>Wraps this vault's key to another member.</summary>
|
|
/// <remarks>
|
|
/// The one call in this API whose body the server can neither produce nor check. It stores a sealed
|
|
/// key and a signature over a tuple it never verifies — see docs/crypto.md §6 and §7 — which is
|
|
/// exactly why sharing is a client operation with a server-side record rather than a server feature.
|
|
/// </remarks>
|
|
internal sealed class IssueVaultGrantEndpoint(
|
|
ICurrentUserContext currentUser,
|
|
IVaultAccessService vaultAccess,
|
|
VaultGrantService grants)
|
|
: Endpoint<IssueVaultGrantRequest, Results<NoContent, NotFound, ProblemHttpResult>>
|
|
{
|
|
/// <inheritdoc />
|
|
public override void Configure()
|
|
{
|
|
Post("/api/v1/vaults/{vaultId:guid}/grants");
|
|
|
|
Policies(Auth.EnrolledPolicy);
|
|
|
|
Description(b => b
|
|
.WithName("IssueVaultGrant")
|
|
.WithSummary("Records a vault key wrapped to another member.")
|
|
.WithTags("Vaults"));
|
|
}
|
|
|
|
/// <inheritdoc />
|
|
public override async Task<Results<NoContent, NotFound, ProblemHttpResult>> ExecuteAsync(
|
|
IssueVaultGrantRequest req,
|
|
CancellationToken ct)
|
|
{
|
|
var user = await currentUser.GetOrProvisionAsync(ct).ConfigureAwait(false);
|
|
var access = await vaultAccess
|
|
.ResolveAsync(user.Id, Route<Guid>("vaultId"), ct)
|
|
.ConfigureAwait(false);
|
|
|
|
if (!access.Granted || !access.Permissions.HasFlag(PermissionFlags.Read))
|
|
{
|
|
return TypedResults.NotFound();
|
|
}
|
|
|
|
if (!access.Permissions.HasFlag(PermissionFlags.Share))
|
|
{
|
|
return Problems.Coded(
|
|
StatusCodes.Status403Forbidden,
|
|
ProblemCodes.Forbidden,
|
|
"You do not have permission to share this vault.");
|
|
}
|
|
|
|
try
|
|
{
|
|
await grants.IssueGrantAsync(user, access.Vault!, req, ct).ConfigureAwait(false);
|
|
|
|
// 204. There is nothing to return that the caller does not already hold — it produced
|
|
// the wrap — and echoing the sealed key back would put it on the wire twice for nothing.
|
|
return TypedResults.NoContent();
|
|
}
|
|
catch (VaultGrantInvalidException exception)
|
|
{
|
|
return Problems.Coded(
|
|
StatusCodes.Status400BadRequest, ProblemCodes.InvalidVaultGrant, exception.Message);
|
|
}
|
|
}
|
|
}
|
|
|
|
/// <summary>Moves this vault to a fresh key.</summary>
|
|
/// <remarks>
|
|
/// Gated on Share rather than on a rotation permission of its own. Rotating decides who can read what
|
|
/// is written next, which is the same question sharing and withdrawing answer, and a fourth permission
|
|
/// would be a distinction nobody administering a team would be able to explain.
|
|
/// </remarks>
|
|
internal sealed class RekeyVaultEndpoint(
|
|
ICurrentUserContext currentUser,
|
|
IVaultAccessService vaultAccess,
|
|
VaultGrantService grants)
|
|
: Endpoint<RekeyVaultRequest, Results<Ok<VaultSummary>, NotFound, ProblemHttpResult>>
|
|
{
|
|
/// <inheritdoc />
|
|
public override void Configure()
|
|
{
|
|
Post("/api/v1/vaults/{vaultId:guid}/rekey");
|
|
|
|
Policies(Auth.EnrolledPolicy);
|
|
|
|
Description(b => b
|
|
.WithName("RekeyVault")
|
|
.WithSummary("Advances this vault's key generation, wrapped to the caller.")
|
|
.WithTags("Vaults"));
|
|
}
|
|
|
|
/// <inheritdoc />
|
|
public override async Task<Results<Ok<VaultSummary>, NotFound, ProblemHttpResult>> ExecuteAsync(
|
|
RekeyVaultRequest req,
|
|
CancellationToken ct)
|
|
{
|
|
var user = await currentUser.GetOrProvisionAsync(ct).ConfigureAwait(false);
|
|
var access = await vaultAccess
|
|
.ResolveAsync(user.Id, Route<Guid>("vaultId"), ct)
|
|
.ConfigureAwait(false);
|
|
|
|
if (!access.Granted || !access.Permissions.HasFlag(PermissionFlags.Read))
|
|
{
|
|
return TypedResults.NotFound();
|
|
}
|
|
|
|
if (!access.Permissions.HasFlag(PermissionFlags.Share))
|
|
{
|
|
return Problems.Coded(
|
|
StatusCodes.Status403Forbidden,
|
|
ProblemCodes.Forbidden,
|
|
"You do not have permission to share this vault, so you cannot rotate its key.");
|
|
}
|
|
|
|
try
|
|
{
|
|
var summary = await grants
|
|
.RekeyAsync(user, access.Vault!, (int)access.Permissions, req, ct)
|
|
.ConfigureAwait(false);
|
|
|
|
return TypedResults.Ok(summary);
|
|
}
|
|
catch (VaultGrantInvalidException exception)
|
|
{
|
|
return Problems.Coded(
|
|
StatusCodes.Status400BadRequest, ProblemCodes.InvalidVaultGrant, exception.Message);
|
|
}
|
|
}
|
|
}
|
|
|
|
/// <summary>Withdraws a member's key to this vault.</summary>
|
|
/// <remarks>
|
|
/// 404 for a member who holds no live grant, rather than a bland 204, for the reason device
|
|
/// revocation gives: "revoked" is what the user reads, and reading it about the wrong account is
|
|
/// worse than being told to look again. A caller driving towards "they cannot read this any more"
|
|
/// can treat 404 as having arrived.
|
|
/// </remarks>
|
|
internal sealed class RevokeVaultGrantEndpoint(
|
|
ICurrentUserContext currentUser,
|
|
IVaultAccessService vaultAccess,
|
|
VaultGrantService grants)
|
|
: EndpointWithoutRequest<Results<NoContent, NotFound, ProblemHttpResult>>
|
|
{
|
|
/// <inheritdoc />
|
|
public override void Configure()
|
|
{
|
|
Delete("/api/v1/vaults/{vaultId:guid}/grants/{userId:guid}");
|
|
|
|
Policies(Auth.EnrolledPolicy);
|
|
|
|
Description(b => b
|
|
.WithName("RevokeVaultGrant")
|
|
.WithSummary("Withdraws a member's key to this vault. Blocks future reads only.")
|
|
.WithTags("Vaults"));
|
|
}
|
|
|
|
/// <inheritdoc />
|
|
public override async Task<Results<NoContent, NotFound, ProblemHttpResult>> ExecuteAsync(
|
|
CancellationToken ct)
|
|
{
|
|
var user = await currentUser.GetOrProvisionAsync(ct).ConfigureAwait(false);
|
|
var access = await vaultAccess
|
|
.ResolveAsync(user.Id, Route<Guid>("vaultId"), ct)
|
|
.ConfigureAwait(false);
|
|
|
|
if (!access.Granted || !access.Permissions.HasFlag(PermissionFlags.Read))
|
|
{
|
|
return TypedResults.NotFound();
|
|
}
|
|
|
|
if (!access.Permissions.HasFlag(PermissionFlags.Share))
|
|
{
|
|
return Problems.Coded(
|
|
StatusCodes.Status403Forbidden,
|
|
ProblemCodes.Forbidden,
|
|
"You do not have permission to share this vault.");
|
|
}
|
|
|
|
try
|
|
{
|
|
var revoked = await grants
|
|
.RevokeGrantAsync(user, access.Vault!, Route<Guid>("userId"), ct)
|
|
.ConfigureAwait(false);
|
|
|
|
return revoked ? TypedResults.NoContent() : TypedResults.NotFound();
|
|
}
|
|
catch (VaultGrantInvalidException exception)
|
|
{
|
|
return Problems.Coded(
|
|
StatusCodes.Status400BadRequest, ProblemCodes.InvalidVaultGrant, exception.Message);
|
|
}
|
|
}
|
|
}
|