Protect paging cookies

Runs the sample. Generated for this page; it reads the connection string from the environment and first remakes the sample database from sample-schema.json.

using ArxSamples.DynamoDb;
using ArxSamples.DynamoDb.Operations.RetrieveMultiple.AdvancedCases;

// The connection string comes from the environment, never from the code (see "Configure the connection").
var connectionString = Environment.GetEnvironmentVariable("ARX_SAMPLES_DYNAMODB")
    ?? throw new InvalidOperationException("Set the ARX_SAMPLES_DYNAMODB environment variable to your Amazon DynamoDB connection string.");

var dbContext = new SampleContext(connectionString);

// Every run starts from the sample data: this deletes and makes again what sample-schema.json lists
// (save the file in the project folder, see Get started).
await dbContext.Direct.ResetAsync();

await new Advanced3_ProtectPagingCookies().RunAsync(dbContext);

The sample, as it is in the repository.

using System.Text;
using Amazon.DynamoDBv2;
using ARX.SDK;
using ARX.SDK.DynamoDb.Model;
using ARX.SDK.DynamoDb.Services;
using ARX.SDK.Query;
using ARX.SDK.Services;

using static ArxSamples.DynamoDb.SampleOutput;

namespace ArxSamples.DynamoDb.Operations.RetrieveMultiple.AdvancedCases;

/// <summary>
/// Protect the paging cookies your API hands to clients, in three scenarios: sealed by default, one key shared by every
/// instance of the application, and plain cookies when you choose them.
/// </summary>
/// <remarks>
/// A paging cookie carries the last item's key values: here a customer's email. A client could decode it, and change it
/// to page from somewhere else. So ARX seals cookies by default (encrypted and authenticated, AES-256-GCM): a client can
/// neither read nor change one. Without a key from you, ARX seals with a random key of the process, which every service in
/// the process shares: right for one process. When several instances serve the same clients, or cookies must survive a
/// restart, give every instance the same <c>PagingCookieKey</c> (32 bytes or more, from your configuration or secret
/// store); otherwise a cookie that reaches another instance is ARX1001. <c>PagingCookieProtection</c> can also be
/// <c>Signed</c> (readable, not changeable) or <c>Plain</c>.
/// </remarks>
public sealed class Advanced3_ProtectPagingCookies : ISample
{
    public string Name => "retrieve-multiple-advanced-3-protect-paging-cookies";

    public string Title => "Protect paging cookies";

    public async Task RunAsync(SampleContext dbContext)
    {
        var orders = Enumerable.Range(1, 6).Select(i =>
        {
            var order = new ArxEntity("sales_order");
            order["customer_id"] = "ana@example.com";
            order["order_number"] = $"SO-D44{i}";
            order["status"] = "OPEN";
            order["ordered_on"] = "2026-11-10";
            return order;
        }).ToList();
        await dbContext.Service.CreateMultipleAsync(orders);

        await Scenario1_SealedByDefaultAsync(dbContext.Service);

        await Scenario2_ASharedKeyForEveryInstanceAsync(dbContext.Client, dbContext.Model);

        await Scenario3_PlainWhenYouChooseItAsync(dbContext.Client, dbContext.Model);
    }

    private static ArxQueryExpression Query(string? cookie = null)
    {
        var query = new ArxQueryExpression("sales_order");
        query.ColumnSet.AddColumns("order_number");
        query.Criteria.AddCondition("customer_id", ArxConditionOperator.Equal, "ana@example.com");
        query.PageInfo = new ArxPagingInfo { Count = 2, PagingCookie = cookie };
        return query;
    }

    // What a client could read from a cookie: its bytes as text.
    private static string Readable(string cookie)
    {
        var base64 = cookie.Replace('-', '+').Replace('_', '/');
        return Encoding.UTF8.GetString(Convert.FromBase64String(base64.PadRight(base64.Length + (4 - base64.Length % 4) % 4, '=')));
    }

    /// <summary>1. The default: the cookie hides the email it pages by, and the next page reads it.</summary>
    private static async Task Scenario1_SealedByDefaultAsync(ArxDynamoDbService service)
    {
        Step("1. Sealed by default");

        var first = await service.RetrieveMultipleAsync(Query());
        Show($"protection {service.PagingCookieProtection}; the cookie shows the email: {Readable(first.PagingCookie).Contains("ana@example.com")}");

        var second = await service.RetrieveMultipleAsync(Query(first.PagingCookie));
        Show($"next page: {string.Join(", ", second.Entities.Select(x => x["order_number"]))}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "PK" = 'CUSTOMER#ana@example.com' AND begins_with("SK", 'ORDER#')
         * -- Expect: 6 items, SO-D441 to SO-D446; the second page holds SO-D443 and SO-D444.
         * ===========================================================
         */
    }

    /// <summary>2. Two instances of the application: with one shared key, either reads the other's cookies; with their own, it is ARX1001.</summary>
    private static async Task Scenario2_ASharedKeyForEveryInstanceAsync(IAmazonDynamoDB client, ArxDynamoModel model)
    {
        Step("2. One key for every instance");

        // In production the key comes from configuration or a secret store, the same on every instance.
        var sharedKey = ArxPagingCookie.NewKey();
        var instanceA = new ArxDynamoDbService(client, model, SampleModel.Catalog()) { PagingCookieKey = sharedKey };
        var instanceB = new ArxDynamoDbService(client, model, SampleModel.Catalog()) { PagingCookieKey = sharedKey };

        var first = await instanceA.RetrieveMultipleAsync(Query());
        var second = await instanceB.RetrieveMultipleAsync(Query(first.PagingCookie));
        Show($"instance B continued: {string.Join(", ", second.Entities.Select(x => x["order_number"]))}");

        var withItsOwnKey = new ArxDynamoDbService(client, model, SampleModel.Catalog()) { PagingCookieKey = ArxPagingCookie.NewKey() };

        try
        {
            await withItsOwnKey.RetrieveMultipleAsync(Query(first.PagingCookie));
        }
        catch (ArxValidationException exception)
        {
            ShowError(exception);
        }

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "PK" = 'CUSTOMER#ana@example.com' AND begins_with("SK", 'ORDER#')
         * -- Expect: 6 items (nothing is written: the check is in the cookie).
         * ===========================================================
         */
    }

    /// <summary>3. Plain cookies: readable and changeable by clients, so only where their values aren't sensitive.</summary>
    private static async Task Scenario3_PlainWhenYouChooseItAsync(IAmazonDynamoDB client, ArxDynamoModel model)
    {
        Step("3. Plain, when you choose it");

        var service = new ArxDynamoDbService(client, model, SampleModel.Catalog()) { PagingCookieProtection = ArxPagingCookieProtection.Plain };
        var first = await service.RetrieveMultipleAsync(Query());
        Show($"the cookie shows the email: {Readable(first.PagingCookie).Contains("ana@example.com")}");

        /* ===========================================================
         * [DIRECT QUERY CHECK]
         * -----------------------------------------------------------
         * SELECT "order_number" FROM "crm" WHERE "PK" = 'CUSTOMER#ana@example.com' AND begins_with("SK", 'ORDER#')
         * -- Expect: 6 items.
         * ===========================================================
         */
    }
}

What every sample is given: the connection string (and the ISample interface the samples implement).

namespace ArxSamples.DynamoDb;

/// <summary>One documentation sample: a scenario a real application has, shown end to end.</summary>
public interface ISample
{
    /// <summary>The name to run it alone: <c>dotnet run -- &lt;name&gt;</c>.</summary>
    string Name { get; }

    /// <summary>One line on what it shows.</summary>
    string Title { get; }

    Task RunAsync(SampleContext dbContext);
}

/// <summary>
/// What a sample is given. Every sample gets the connection string; the application's service and catalog
/// (SampleContext.Application.cs) and the plain AWS SDK read-back helper (SampleContext.Direct.cs) live in their own
/// files, so a sample needs only the files it uses.
/// </summary>
public sealed partial class SampleContext
{
    public SampleContext(string connectionString)
    {
        ConnectionString = connectionString;
    }

    public string ConnectionString { get; }
}

How the samples print: Step for each scenario, Show for what it did, ShowError for an error caught on purpose.

using ARX.SDK;

namespace ArxSamples.DynamoDb;

/// <summary>How the samples print: a numbered step for each scenario, then what it did.</summary>
public static class SampleOutput
{
    /// <summary>The start of a scenario: <c>Step("1. By the id Create returned")</c>.</summary>
    public static void Step(string text) => Console.WriteLine($"  > {text}");

    /// <summary>What the scenario did.</summary>
    public static void Show(string text) => Console.WriteLine($"      {text}");

    /// <summary>An ARX error the scenario caught on purpose.</summary>
    public static void ShowError(ArxException exception)
        => Console.WriteLine($"      caught {exception.GetType().Name}: {exception.Message}");
}

The application's DynamoDB client, model, schema catalog and ARX service, created once and shared by the samples.

using Amazon.DynamoDBv2;
using Amazon.Runtime;
using ARX.SDK.DynamoDb.Model;
using ARX.SDK.DynamoDb.Services;
using ARX.SDK.Services;

namespace ArxSamples.DynamoDb;

/// <summary>The application's DynamoDB client, model, catalog and ARX service, shared by the samples.</summary>
public sealed partial class SampleContext
{
    private IAmazonDynamoDB? _client;
    private ArxDynamoModel? _model;
    private ArxSchemaCatalog? _catalog;
    private ArxDynamoDbService? _service;

    /// <summary>
    /// The DynamoDB client for the endpoint the connection string names. Credentials come from the AWS SDK's own chain
    /// (environment, profile, role), never from code; DynamoDB Local on this machine accepts any, so a local endpoint
    /// without credentials in the environment gets placeholder ones.
    /// </summary>
    public IAmazonDynamoDB Client => _client ??= CreateClient(ConnectionString);

    /// <summary>How the entities are laid out (SampleModel.cs).</summary>
    public ArxDynamoModel Model => _model ??= SampleModel.Build();

    /// <summary>The ids, lookups and selection sets (SampleModel.cs).</summary>
    public ArxSchemaCatalog Catalog => _catalog ??= SampleModel.Catalog();

    /// <summary>One service for the whole application: it holds no connection.</summary>
    public ArxDynamoDbService Service => _service ??= new ArxDynamoDbService(Client, Model, Catalog);

    private static IAmazonDynamoDB CreateClient(string endpoint)
    {
        var config = new AmazonDynamoDBConfig { ServiceURL = endpoint, AuthenticationRegion = Environment.GetEnvironmentVariable("AWS_REGION") ?? "us-east-1" };
        var local = Uri.TryCreate(endpoint, UriKind.Absolute, out var uri) && (uri.IsLoopback || uri.Host == "localhost");

        return local && Environment.GetEnvironmentVariable("AWS_ACCESS_KEY_ID") == null
            ? new AmazonDynamoDBClient(new BasicAWSCredentials("local", "local"), config)
            : new AmazonDynamoDBClient(config);
    }
}

How the application lays out its entities in Amazon DynamoDB, and its schema catalog.

using ARX.SDK.DynamoDb.Model;
using ARX.SDK.Services;

namespace ArxSamples.DynamoDb;

/// <summary>
/// How the application lays out its entities in DynamoDB, in both designs, and its schema catalog.
/// </summary>
/// <remarks>
/// <para>
/// <b>A table per entity:</b> <c>product</c> has a table of its own, keyed by its <c>sku</c>; <c>lead</c> by its
/// <c>email</c>. The entity's attributes are the item's, keys included.
/// </para>
/// <para>
/// <b>A single table:</b> <c>crm</c> holds customers and their orders together. Each entity's keys are templates:
/// a customer is <c>PK = CUSTOMER#{customer_id}</c>, <c>SK = PROFILE</c>; an order shares its customer's partition,
/// <c>SK = ORDER#{order_number}</c>, so one query reads a customer with its orders. ARX writes the keys, the
/// <c>entity_type</c> attribute that tells the items apart, and the index keys (<c>GSI1</c>: orders by status and date).
/// </para>
/// <para>
/// <b>Write sharding:</b> <c>events</c> spreads the page views of one page over four partitions (a suffix from a hash of
/// the time), so a popular page doesn't overload one partition; ARX reads them back merged.
/// </para>
/// <para>
/// <b>The catalog</b> declares each entity's id (supplied: DynamoDB generates none, so ids come from the application),
/// the lookup from an order to its customer, the customer's display name and the order statuses.
/// </para>
/// </remarks>
public static class SampleModel
{
    public static ArxDynamoModel Build() => ArxDynamoModel.Create()
        .Table("product", partitionKey: "sku")
        .Table("lead", partitionKey: "email")
        .SingleTable("crm", "PK", "SK", crm => crm
            .Entity("customer", pk: "CUSTOMER#{customer_id}", sk: "PROFILE")
            .Entity("sales_order", pk: "CUSTOMER#{customer_id}", sk: "ORDER#{order_number}")
            .Index("GSI1", "GSI1PK", "GSI1SK")
            .EntityIndex("sales_order", "GSI1", pk: "STATUS#{status}", sk: "{ordered_on}"))
        .SingleTable("events", "PK", "SK", events => events
            .Entity("page_view", pk: "PAGE#{page}", sk: "VIEW#{viewed_at}"))
        .WriteSharding("page_view", shards: 4, by: "viewed_at")
        .Build();

    public static ArxSchemaCatalog Catalog() => ArxSchemaCatalog.Create()
        .Table("product", ArxIdColumn.Supplied<string>("sku"))
        .DisplayName("product", "name")
        .Table("lead", ArxIdColumn.Supplied<string>("email"))
        .Table("customer", ArxIdColumn.Supplied<string>("customer_id"))
        .DisplayName("customer", "name")
        .Table("sales_order", ArxIdColumn.Supplied<string>("order_number"))
        .Lookup("sales_order", "customer_id", "customer")
        .Table("page_view", ArxIdColumn.Supplied<string>("viewed_at"))
        .Add("OrderStatus", ArxSelectionSetKind.String, ("OPEN", "Open"), ("SHIPPED", "Shipped"), ("CANCELLED", "Cancelled"))
        .Build();
}

The plain AWSSDK.DynamoDBv2 read-back helper, for the samples that show what Amazon DynamoDB stored.

namespace ArxSamples.DynamoDb;

/// <summary>The plain AWS SDK outside ARX, for the samples that show what DynamoDB stored.</summary>
public sealed partial class SampleContext
{
    private DynamoDirectHelper? _direct;

    /// <summary>The plain AWS SDK outside ARX, used only to reset the tables and to show what was stored.</summary>
    public DynamoDirectHelper Direct => _direct ??= new DynamoDirectHelper(Client);
}

Plain AWSSDK.DynamoDBv2, not part of ARX: reads rows back so a sample can show what Amazon DynamoDB stored.

using System.Text.Json;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;

namespace ArxSamples.DynamoDb;

/// <summary>
/// The plain AWS SDK, outside ARX: it resets the sample tables from Schema/sample-schema.json and runs the PartiQL
/// statements of the samples' checks. Samples never write through it.
/// </summary>
public sealed class DynamoDirectHelper
{
    private readonly IAmazonDynamoDB _client;

    public DynamoDirectHelper(IAmazonDynamoDB client)
    {
        _client = client;
    }

    /// <summary>
    /// The sample schema: Schema/sample-schema.json next to the program (the samples' own project), or sample-schema.json
    /// in the project folder (a sample copied from its page, as Get started says).
    /// </summary>
    private static string SchemaPath()
    {
        var candidates = new[]
        {
            Path.Combine(AppContext.BaseDirectory, "Schema", "sample-schema.json"),
            Path.Combine(Directory.GetCurrentDirectory(), "sample-schema.json"),
            Path.Combine(Directory.GetCurrentDirectory(), "Schema", "sample-schema.json")
        };

        return candidates.FirstOrDefault(File.Exists)
            ?? throw new FileNotFoundException("sample-schema.json isn't in the project folder: download it from the Get started page and save it next to Program.cs.");
    }

    /// <summary>
    /// Deletes and creates every table sample-schema.json lists, with its keys and indexes; no other table is touched. It
    /// runs only against DynamoDB Local (a localhost endpoint): set ARX_SAMPLES_ALLOW_REMOTE_RESET=1 to reset the sample
    /// tables of a real AWS account deliberately.
    /// </summary>
    public async Task ResetAsync()
    {
        var endpoint = _client.Config.ServiceURL ?? string.Empty;
        var local = Uri.TryCreate(endpoint, UriKind.Absolute, out var uri) && (uri.IsLoopback || uri.Host.Equals("localhost", StringComparison.OrdinalIgnoreCase));

        if (!local && Environment.GetEnvironmentVariable("ARX_SAMPLES_ALLOW_REMOTE_RESET") != "1")
        {
            throw new InvalidOperationException(
                $"The samples reset their tables (delete and create them), and the client points at '{(endpoint.Length == 0 ? "AWS" : endpoint)}', not DynamoDB Local. "
                + "Point it at http://localhost:8000 (or your DynamoDB Local port), or set ARX_SAMPLES_ALLOW_REMOTE_RESET=1 to reset the sample tables there.");
        }

        using var schema = JsonDocument.Parse(await File.ReadAllTextAsync(SchemaPath()));

        foreach (var table in schema.RootElement.GetProperty("tables").EnumerateArray())
        {
            var name = table.GetProperty("name").GetString()!;

            try
            {
                await _client.DeleteTableAsync(name);
            }
            catch (ResourceNotFoundException)
            {
            }

            var definitions = new Dictionary<string, string>();
            var keys = Keys(table, definitions);
            var request = new CreateTableRequest { TableName = name, KeySchema = keys, BillingMode = BillingMode.PAY_PER_REQUEST };

            if (table.TryGetProperty("indexes", out var indexes))
            {
                request.GlobalSecondaryIndexes = indexes.EnumerateArray().Select(index => new GlobalSecondaryIndex
                {
                    IndexName = index.GetProperty("name").GetString(),
                    KeySchema = Keys(index, definitions),
                    Projection = new Projection { ProjectionType = ProjectionType.ALL }
                }).ToList();
            }

            request.AttributeDefinitions = definitions.Select(x => new AttributeDefinition(x.Key, x.Value)).ToList();
            await _client.CreateTableAsync(request);
        }
    }

    private static List<KeySchemaElement> Keys(JsonElement table, Dictionary<string, string> definitions)
    {
        var keys = new List<KeySchemaElement>();
        var pk = table.GetProperty("partitionKey").GetString()!;
        definitions[pk] = table.TryGetProperty("partitionKeyType", out var pkType) ? pkType.GetString()! : "S";
        keys.Add(new KeySchemaElement(pk, KeyType.HASH));

        if (table.TryGetProperty("sortKey", out var sk))
        {
            definitions[sk.GetString()!] = table.TryGetProperty("sortKeyType", out var skType) ? skType.GetString()! : "S";
            keys.Add(new KeySchemaElement(sk.GetString(), KeyType.RANGE));
        }

        return keys;
    }

    /// <summary>The items a PartiQL statement finds, as JSON, one line each.</summary>
    public async Task<IReadOnlyList<string>> QueryAsync(string statement)
    {
        var response = await _client.ExecuteStatementAsync(new ExecuteStatementRequest { Statement = statement, ConsistentRead = true });
        return response.Items.Select(item => JsonSerializer.Serialize(item.ToDictionary(x => x.Key, x => x.Value.S ?? x.Value.N ?? (x.Value.IsBOOLSet ? x.Value.BOOL.ToString() : "…")))).ToList();
    }
}

  > 1. Sealed by default
      protection Sealed; the cookie shows the email: False
      next page: SO-D443, SO-D444
  > 2. One key for every instance
      instance B continued: SO-D443, SO-D444
      caught ArxValidationException: ARX1001 InvalidArgument: PageInfo.PagingCookie isn't a cookie DynamoDb wrote for this query: it was changed, or sealed with another key: another instance of the application, or one before a restart. Give every instance the same PagingCookieKey to page across them. Pass the PagingCookie of the previous page unchanged, or null for the first page.
  > 3. Plain, when you choose it
      the cookie shows the email: True